Humagen agentic workspace: product and design spec¶
Prepared design, October 2026.
Status: mostly built. Checked against main on 2026-11-19. The
gap analysis was reviewed on
October 24, 2026 and still lists as not built several items that are on main
now. Where the two disagree, the list below is the newer one. Where this spec
and AGENTS.md disagree on presentation, AGENTS.md wins (see
Identity).
What is built¶
Each item was read in code on main. No screen was opened and no test was run
for this list.
| Decision | State | Evidence |
|---|---|---|
| Action policy: Allow, Ask, Never by category | Built | pkg/operations/operations.go; enforced on agent calls in internal/platform/handoffs.go |
| Pause, manager, stop rules and reminders | Built | pkg/operations/operations.go |
| Handoff contracts: goal, done-when, due; a cycle or more than three hops goes to a person | Built | pkg/operations/operations.go, internal/platform/handoffs.go |
| Standing assignments | Built | pkg/operations/operations.go (Assignment) |
| Source lifecycle with attempts and last good copy | Built | pkg/knowledge/lifecycle.go (#80) |
| Agent network and Context health | Built | apps/web/src/AgentNetwork.tsx, apps/web/src/ContextHealth.tsx, both mounted in apps/web/src/App.tsx |
| Conversation fork and "Bring back result" | Built | internal/platform/forks.go (#82) |
| Project fork | Built | internal/platform/project_forks.go |
| Integration link modes: Suggest, Auto-link, Off | Built | pkg/sourcelinks/links.go |
| Slack bridge: two-way, inbound only, outcomes only | Built | pkg/projects/channels.go |
| Dry run for a new agent | Built | internal/platform/agent_setup.go, internal/platform/converse.go |
| Memory expiry | Built | pkg/memory/memory.go |
| Notification modes and digest | Built | pkg/notifications/notifications.go |
| Quick switcher | Built | apps/web/src/QuickSwitcher.tsx |
| Skill promotion | Built | internal/platform/skill_library.go, apps/web/src/SkillsLibrary.tsx |
| Initiatives | Partly built | A flag on a Team project (pkg/projects/projects.go) and a rollup (internal/platform/project_rollup.go). Initiative agents across child projects: not confirmed |
| Personal agents | Partly built | apps/web/src/PersonalAgents.tsx, pkg/projects/personal.go. Promotion of a personal agent to a project: not confirmed |
| Conversation re-homing after agents ran | Not built | Refused on purpose: ErrStaysInProject and ErrStaysInChannel in internal/platform/threads.go |
Summary and principles¶
Humagen is a project-based workspace where people and agents work together. Projects hold the people, agents, context, skills, memory and outcomes for one body of work. A workspace-level control plane lets one person oversee far more delegated work without watching every step.
- Outcome first, steps on demand. Every agent result leads with the recommendation, decisions, deliverables and next action. Steps, tool calls and handoffs are one click away.
- One room per body of work. Projects and channels are the same concept at two sizes. A conversation, its agents, its context and its outputs live together.
- Every object says what it is and whose it is. People, agents, skills, memories and sources each have one fixed mark. Every configurable thing carries a scope chip.
- Visible provenance. Any fact an agent uses shows where it came from, whether it is live or a snapshot, and when it was last good.
- People decide; agents carry. Agents act within explicit autonomy (Allow, Ask, Never). Anything outside it becomes a decision routed to a named person.
- Quiet by default, loud on exceptions. The interface is calm until a decision, permission, failure or stale source needs a person.
- Narrower can tighten, never loosen. Settings inherit Workspace, Project, Agent, Personal, and a lower level can only be stricter.
Mental model and information architecture¶
A workspace contains projects, a shared Library, the Operations control plane and a personal layer (You). Projects are where work happens; everything else feeds or oversees them.
| Area | Holds |
|---|---|
| Projects | Channels and subchannels, conversations, members and agents, context sources, project skills, project memory, outcomes and decisions |
| Library | Skills (versioned) and memory (reviewed), each scoped to workspace, project or person |
| Operations | Needs you, Agents, Agent network, Context health, Integrations, Policies, Usage, Audit log |
| You | Profile and briefing style, notifications, personal agents, personal skills and memory, connected accounts, privacy defaults |
- A conversation is the unit of work. It can start private and be added to a project later; its runs, Activity, sources and deliverables move with it.
- Inside a project the left nav shows its channels and conversations, each listing the agents that took part. The conversation's right side holds Context, People and Settings (which holds Activity).
Objects, scopes and identity¶
Each object type has one mark used everywhere.
| Object | Mark in this repo | What it is |
|---|---|---|
| Person | Circle (PersonMark) |
A human member; the only one who can decide |
| Agent | AgentMark colour, never letters in a box |
A worker with a role, assignments and autonomy |
| Skill | Badge with the skill icon | A reusable, versioned way of doing a job |
| Memory | Badge with the bookmark icon | A durable fact, decision or preference with provenance |
| Source | Badge with the database icon | Context from outside: indexed, live or hybrid |
| Decision | Check-circle with the accent | A choice routed to a named person |
| Handoff | Arrow | Work passed between agents, with a contract |
The canvas boards draw agents as initials in rounded squares. That predates
this review and conflicts with AGENTS.md ("Agents are told apart by color, not
by letters in boxes"). Implementations use AgentMark; the boards' layouts and
flows still apply.
Scope chips. Skills, memories, sources, policies and agents carry a neutral chip: icon and word (Workspace, a project name, an agent name, or "Only you"). Colour never carries scope on its own.
Core flows¶
- Source change to decision (the delegated-work loop). A source changes; Monitor Agent detects it and hands off to Launch Planner; Launch Planner assesses impact and asks Ops Agent to draft, held for approval; the person decides in the conversation (approve or redirect); Ops Agent acts within its autonomy; the decision is saved to project memory. Every step writes to Activity; only the decision reaches the person.
- Start private, add to a project. The dialog shows the audience change before confirming, what moves (messages, runs and Activity, sources), and any private source that would become visible, with "share a summary" as the default. The move is logged with before and after audience.
- Create an agent. Role, assignments, skills and context, autonomy (pre-filled and locked by policy), review, then a dry run with every action forced to Ask.
- Teach a skill. Save a good outcome as a skill draft, test, publish as v1 with personal or project scope, promote to workspace when it proves itself.
- Remember and forget. Approved decisions are saved automatically; other memories are suggestions until a person keeps them; forget is immediate and logged.
Agents and how they talk to each other¶
| Part | Holds |
|---|---|
| Role | One plain-language job description |
| Standing assignments | Trigger and action pairs that keep work going across sessions |
| Skills | Versioned skills it may run |
| Context | Sources it may read, with mode and freshness |
| Autonomy | Allow, Ask or Never per action category, inherited from policy |
| Handoffs | Agents it may hand work to |
| Escalation and limits | Who it asks, reminders, stop rules, run budget |
| Manager | The person accountable for it |
States: Working, Waiting on people, Watching, Paused, Failed; always words, not colour alone.
Handoff contract. Goal, inputs (attached objects), due and done-when, with states Requested, Accepted, In progress, Result, Blocked, Needs a person. Agents hand off only to allowed agents; a chain over 3 hops or any loop escalates to the manager; a blocked handoff names its blocker and raises one Needs-you item.
Where coordination shows. The conversation shows the outcome and one line ("3 agents coordinated, 2 handoffs"). Activity shows each step. The Agent network shows who hands to whom, volumes, waiting time and blocked threads.
Context: provenance and the sync lifecycle¶
Every source shows origin and owner, access mode, last good sync, status and dependents. Lifecycle: Connected, Importing, Indexing, Available, then for live sources Syncing and In sync, with a side state Needs attention (auth expired, quota, schema changed, unsupported files). A failing source keeps its last good copy; agents say they used it. Repeated failure or a stale relied-on source raises one Needs-you item per cause, and dependent assignments pause past the agent's stop rule (default 24 hours).
Context access modes¶
| Indexed | Live search | Hybrid | |
|---|---|---|---|
| What happens | Copied and indexed, kept in sync | Queried when an agent asks | Pinned pages indexed, the rest live |
| Freshness | Last good sync | Current at query time | Per part |
| Permissions | Project rules on the copy | The asker's own access, checked each time | Per part |
| Source down | Works from last good copy | Unavailable, said so | Pinned part works |
| Default for | Drive folders, uploads, GitHub issues | Notion workspaces, GitHub code | Notion with a few canonical pages |
Answers cite each source with its mode. Live results the asker cannot see are never shown to them.
Skills and memory¶
- Skills: name, purpose, inputs and outputs, allowed tools, steps, version. Scope Personal, Project, Workspace; promotion is logged; edits create a new version; test runs force every action to Ask.
- Memory: Decisions, Facts, Preferences, People and owners. Each item shows scope, provenance, status (Confirmed, Suggested, Expires) and use count. Agents only suggest project memory. Personal memory never enters projects unless the person allows it.
User-level configuration (You)¶
| Panel | Controls |
|---|---|
| Profile | Name, role, how agents should brief you |
| Notifications | Per event kind: immediately, digest or off; quiet hours |
| My agents | Personal agents, their autonomy, pause, add to a project |
| Skills and memory | Personal skills; "remember how I work"; personal memory in projects (off by default) |
| Connected accounts | Granted scopes, last agent use, disconnect |
| Privacy and defaults | New conversations start private; private sources move as a summary |
User settings only narrow; they never widen a project or workspace policy.
Control plane (Operations)¶
| Screen | Answers |
|---|---|
| Needs you | What is waiting on me, anywhere? One item per cause |
| Agents | Who is doing what, and how much may they do alone? Pause all |
| Agent settings | What is this agent for and what are its bounds? |
| Agent network | How do agents coordinate, and where does it jam? |
| Context health | Can agents trust what they read? |
| Integrations | Which systems are connected and linked where? |
| Policies | What are the outer bounds? |
| Usage | What does it cost, and how often did it need a person? |
| Audit log | Who did what, when, under which rule, with before and after? |
Hierarchy: initiatives, projects and sub-projects¶
Workspace, Initiative (optional parent), Project, Sub-project, Channel, Conversation. Parents pass down policies (tighten-only), shared sources, skills, read-only memory and initiative agents. Children roll up status, risks, decisions waiting, Needs-you items, usage and promoted memory. An initiative agent acts inside a child only by handing off to that child's agents. Project management offers one tree, a quick switcher, and four ways to start: blank, from a template, fork existing, under an initiative.
Integrations¶
Every external system wraps in through five layers: Connect, Resources, Links to projects, Access mode, Events and actions.
- Link modes: Suggest (default), Auto-link by rule, Off. Rules match existing attributes (repo topic, label, path, contributors; Slack channel prefix; Drive folder; Notion parent page) and can target any level of the hierarchy. Suggestions show why; a resource matching two destinations always goes to Suggest. New rules preview what they would link.
- Slack bridge: two-way, inbound only, or outcomes only. Human messages, outcomes and decision buttons cross; Activity steps and private sources never do. Unmatched Slack users are guests who cannot approve.
- Actions back out (PR comments, Slack posts, page edits) follow the external-message policy and each agent's autonomy, and are audited.
Forking¶
- Conversation fork: "Fork from here" on any message. History up to that message is read-only context; the person picks agents and sources; the original shows a lineage marker; "Bring back result" posts the fork's outcome into the parent for comparison. A fork's pending actions never run in the parent.
- Project fork: copies structure and agent configs; links or copies skills; inherits policies from the new parent; copies no memory unless confirmed items are chosen; re-links live sources after an access check; copies integration rules disabled; copies no conversations by default. Lineage shows on both sides.
Visual tokens¶
The canvas uses Inter, a warm off-white ground (#F6F6F4), one muted blue
accent (#2E5B88) and status tints reserved for meaning, with all text at 4.5:1
or better. In this repo the console's own aui tokens and Page, AgentMark
and copy conventions take precedence; the canvas tokens describe intent, not a
replacement theme. The full token list and icon set are in
design-rules.md and on the Identity and icons board.
System foundations and phasing¶
| Foundation | Records | Unlocks |
|---|---|---|
| Conversation re-homing | Runs, Activity, sources and deliverables move atomically; audience before and after | Start private, add to project |
| Source lifecycle | Per-source state, sync attempts, last good copy, failure reason, cadence | Context health, stop rules, stale-context items |
| Dependency graph | Source to agent, skill, memory, conversation, deliverable | "Used by", one Needs-you item per cause |
| Action policy | Scoped Allow, Ask, Never by action category, tighten-only | Autonomy controls, locks, permission requests |
| Handoff contracts | Due, done-when, contract states, hop counts | Agent network, loop and bottleneck detection |
| Skill and memory store | Versioned skills, scoped memory with provenance and expiry | Library, citations in outcomes |
Phasing: (1) foundation: re-homing, source lifecycle, outcome-first answers; (2) delegation: assignments, action policy, Needs you, roster states, pause; (3) coordination: handoff contracts, Agent network, Context health; (4) compounding: skills library and promotion, memory review and expiry, personal skills and memory, initiatives, forking, integration auto-linking.
Open questions¶
- Is an agent's manager set per project or workspace-wide?
- Should admins see personal agents' activity or only usage totals?
- What are the default run budgets per agent and project, and who raises them?
- Do snapshots expire by default (proposed: flag at 30 days, never delete)?
- Can agents hand off across projects, or only through a person?
- How are external guests represented?