Web product for organizations, projects, and the SDD lifecycle #41

Status

Open epic. Not approved for development. It stays open, and it does not start until epic #37 has a working sdd role slice.

This is possible. The website is a shell over this repo's SDD engine. It is not a second lifecycle and it is not a rewrite of the CLI.

The requirements below are from the product manager. The high-level design is from the architect. The mockups below are the chat and the product tree. The reasons, and the path for adding a feature, are in Mockups. One requirement was tightened so it does not conflict with the lifecycle: the page does not advance a stage by itself, and a role cannot, but the person can continue and the CLI gates still apply.

Requirements

Ids start at R-101 so they do not collide with the greenfield pack.

The site calls the CLI

R-101. Must. Only the local sdd CLI writes specs, decisions, scenarios, designs, tasks, role runs, and releases. The screen shows that stage.

Acceptance: A path that bypasses the CLI leaves the repo and the stage unchanged.

R-102. Must. Refreshing the page does not run sdd next, sdd complete, or createChange. A role cannot run them either. When the person chooses to continue, the site may call sdd next as that person, and the existing gates still apply.

Acceptance: A refresh leaves the stage unchanged. A role call to sdd next leaves it unchanged.

R-103. Must. The site store indexes organizations, members, and project names. Specs, decisions, scenarios, releases, and copied role files stay in the project git repo. Losing the store leaves those files.

Acceptance: Deleting the index leaves the git files in place.

R-104. Must. Jira, Azure DevOps, GitHub, GitLab, Asana, Linear, Aha, Slack, and Teams only seed work or report status, through the connectors in #37. They do not store the stage. A Slack or Teams draft is posted only when the person sends it.

Acceptance: Removing the tracker leaves the stage. An unsent draft stays unposted.

Organization and project

R-105. Must. One person can create an organization and is a member of it. The organization holds members and role templates. No SSO and no hosted computer.

Acceptance: Create works without an identity provider, and the creator is a member.

R-106. Should. "Team" on a decision is a label. It is not an account, a vote, or a second decision.

Acceptance: Adding the label does not change the decision id or the person's words.

R-107. Must. A project is one product, one git repo, and one sdd root. Frontend and backend stay in that root. A second root for the same project is refused.

Acceptance: One root remains, and a second init is refused.

R-108. Must. The site shows the spec from that repo and does not keep its own copy of the spec body.

Acceptance: The screen matches the repo, and the store has no spec body.

Roles

R-109. Must. An organization role template has a name, one job, a description, and an approval boundary. Saving it does not run it and does not copy it into a project. Two jobs are refused.

Acceptance: After save, the project has no new .sdd/roles/ file and no run.

R-110. Must. A project role is that template copied into the project's .sdd/roles/, or a role written for that project alone. Only sdd role from #37 runs it.

Acceptance: Start calls sdd role on that file.

R-111. Must. A role cannot accept a spec, replace a decision, write a QA result, generate a release, run sdd next or sdd complete, or call createChange. Hiding a button is not enough.

Acceptance: After a role run, the spec, the decision, the QA result, the release, and the stage are unchanged unless the person acted.

Lifecycle

R-112. Must. The person's words stay on the page. They see a short reading and accept or correct it. That is the decision. The page does not show a diff, and it does not use Allow once, Always allow, or Deny for this step.

Acceptance: After a correction, the first words and the reading both remain, and those three controls stay hidden.

R-113. Must. Features for the project are gathered through the CLI and are not stored only in the site.

Acceptance: The feature is in the CLI backlog, not only in the store.

R-114. Must. A requirement is an accepted reading (R-112). The list is read from the repo. An unaccepted reading is not an accepted requirement.

Acceptance: An unaccepted reading is absent from the accepted list.

R-115. Must. High-level design shows only modules and services named in the accepted spec, inside this root. It does not create another sdd init.

Acceptance: Every module or service on the screen is named in that spec.

R-116. Must. Low-level design shows tasks only after the design is accepted.

Acceptance: With no accepted design, no task is shown as accepted work.

R-117. Must. The development stop names one action. Deny applies nothing. Allow once runs only that action. A file edit does not commit, push, open a pull request, tag, or deploy unless the stop names that action.

Acceptance: Deny changes nothing. Allowing a file edit does not commit or deploy.

R-118. Must. The person accepts a scenario and records pass or fail in their words, for that change. A role cannot write the result.

Acceptance: The stored result is their words, and a role write is rejected.

R-119. Must. A failing required scenario blocks release until the person accepts that failure. The reading stays the same.

Acceptance: Release stays blocked, and the reading text is unchanged.

R-120. Must. A different project role critiques a draft against the accepted spec. The role that drafted it cannot critique it. Accepting a failed scenario does not change the reading.

Acceptance: The critic and the drafter are different roles, and the reading text is unchanged.

R-121. Must. Pipeline status is the report from Jenkins, GitHub Actions, GitLab CI, Azure Pipelines, or JFrog. A missing build is not shown as passed. The site does not replace those tools.

Acceptance: With no build, the screen says the result was not reported.

R-122. Must. The person chooses what is in the release. The notes use their sentence. Generate release attaches those notes. It does not deploy or push unless the allowed stop names that action.

Acceptance: The notes are their sentence. With no such stop, there is no deploy and no push.

Hierarchy and the chat

R-123. Must. The screen shows the organization, then each product, then that product's backlog. A feature is one backlog id whose workflow is feature. An epic is one backlog id whose workflow is enterprise-feature. Both are ## F-NNN blocks in memory/features.md. The screen does not keep a second backlog.

Acceptance: The tree matches sdd backlog list. An enterprise-feature block is labeled Epic. A feature block is labeled Feature.

R-124. Must. A new product is a new project and a new git repo. The site runs sdd init on that repo only, then sdd greenfield with the person's sentence. Roles draft the vision, the requirements, the feature backlog, and the architecture. The person accepts each. The site runs sdd complete as the person only after those acceptances, which promotes memory/.

Acceptance: Before the vision is accepted, memory/ has no promoted vision. After complete, the backlog is memory/features.md.

R-125. Must. On an existing product, the person adds a feature in the chat with a project role they created. The role drafts the reading. A different role critiques it. The person accepts or corrects. The transcript is not the spec.

Acceptance: The accepted reading is in the repo. Closing the chat leaves the backlog as it was saved.

R-126. Must. After the person accepts and confirms feature or epic, the site appends one ## F-NNN block to memory/features.md as the person. If that file is missing, this confirmed item creates it. Feature sets Workflow feature. Epic sets Workflow enterprise-feature. A role may propose the block and cannot write it.

Acceptance: The block exists only after confirmation, and the workflow field matches that choice.

R-127. Must. The site opens that item with sdd backlog start F-NNN as the person only when no other change is active. createChange sets the active change, so a busy engineer change stays the active one and the new item stays planned. The chat says so. Roles then fill that workflow's artifacts. The site calls sdd next and sdd complete as the person only after the person continues and the gates pass. A role cannot call backlog start, sdd next, sdd complete, or createChange.

Acceptance: With another change active, the backlog status stays planned and the active change id is unchanged. With none active, the new pack exists.

R-128. Must. The chat is with a role the person created. That role guides in plain language and names another role only when it hands off. The accept card, the allow stop, and the QA record appear in the thread. The person's words stay visible there.

Acceptance: The thread shows the guiding role, the decision, and the stop. The spec body is still the repo copy.

Agents

R-129. Must. The organization has an agents screen. A template has a name, one job, a durable description, and one boundary. An empty job or a duplicate name saves nothing and does not overwrite. Save does not run the agent and does not write a product role file.

Acceptance: After save, no product repo has a new .sdd/roles/ file and there is no run.

R-130. Must. The boundary’s first line is only stop: before-accepted-write or stop: after-critique. The screen says, in plain language, that the first stops before anything the person must accept is written, and that the second drafts, a different agent critiques, the author revises, at most three times, and still stops when there are no gaps. The same agent cannot critique itself. A fixed list states the acts a role cannot do, and no control can turn one on: accept a spec, replace a decision, write a QA result, generate a release, sdd next, sdd complete, createChange.

Acceptance: Any other boundary writes nothing. The list is text, not a set of switches.

R-131. Must. Add to a product calls sdd role create as the person with the name, job, description, and boundary. If that name already exists, the call is refused and the file is not overwritten. The copy does not include conversation, memory, or secrets, and it does not start a run. Each product agent has its own conversation. That conversation is not the spec.

Acceptance: The new file is the only new role file. A second add of the same name leaves it unchanged.

R-132. Must. Editing a template does not change copies. The site index stores a revision and the hash of the role file after a successful create or update. A product row says one of: same as the template, template was updated, edited on the product, or both changed. Update this copy shows both versions and, after the person confirms, calls sdd role edit as the person for the job, description, and boundary only. Conversation and memory stay. There is no update-all.

Acceptance: One product can match while another is behind. A refused edit leaves the file and the hash unchanged.

R-133. Must. Skills, connectors, routines, and a permission matrix are not controls on create, edit, or add. The chat stop stays one sentence, with no diff. Allow once, Always allow for that same step, and Deny are the choices on a real stop. An unanswered stop expires after 10 minutes, runs nothing, and saves no rule. Ask first is not a switch on the template. Where it is saved for that same step, it wins over Always allow.

Acceptance: The create screen has no skill picker, no connector picker, and no grant for the acts in R-130.

R-134. Must. A later skill can be invoked only when it is written into the role file. A later connector is a separate screen, outbound only, with no access until it is granted. A secret is not stored in the template or the role file. Neither can grant the acts in R-130.

Acceptance: A skill or connector that exists only on the site row does not run, and a missing connector is not a pass.

Non-goals

Not before sdd role in #37, and not a slice of #37. Not search issues #21–#26. No X, voice, general-purpose assistant, SSO, or hosted multi-tenant computer. Handoffs, approvals, and the task network stay as #37 defined them.

High-level architecture

The website calls the sdd binary in this repo (packages/core, packages/cli). Epic #37 owns the runner, the accuracy loop, approvals, and the task network. sdd agents install remains host stubs and does not create a product role.

Copying a template writes .sdd/roles/<name>.md in the project repo: job and boundary only, not conversation, memory, or secrets. The runner reads that file, not the site row.

flowchart TD
  org[Person creates an organization]
  proj[Person creates one project and one git repo]
  init[CLI inits that repo only]
  copy[Site copies an org role into .sdd/roles]
  words[Person states the need]
  read[Site shows a short reading]
  accept[Person accepts the reading]
  engine[CLI records the decision in git]
  run[Role runner drafts in that root]
  stop[Role stops on one named action]
  allow[Person allows that action or denies it]
  qa[Person records pass or fail]
  gate{Required scenario failed and not accepted?}
  refused[Release refused]
  rel[Person generates the release]
  org --> proj --> init --> copy --> words --> read --> accept --> engine --> run --> stop --> allow --> qa --> gate
  gate -->|Yes| refused
  gate -->|No| rel

The person alone may accept a spec, replace a decision, write QA, generate a release, or run sdd next, sdd complete, or createChange. The engine rejects those for a role even if the page sends them. Each action is bound to one project root.

The site may append a confirmed feature, and may call sdd backlog start, sdd next, and sdd complete as the person, under R-124 and R-127. A role call is still rejected.

flowchart TD
  open[Person opens an existing product]
  say[Person tells a project role the feature]
  draft[Role drafts a reading]
  check[A different role critiques it]
  yes[Person accepts and confirms feature or epic]
  write[CLI appends F-NNN to memory/features.md]
  busy{Another change already active?}
  wait[Feature stays planned]
  start[CLI backlog start as the person]
  fill[Roles fill that workflow]
  cont[Person continues]
  next[CLI sdd next as the person]
  open --> say --> draft --> check --> yes --> write --> busy
  busy -->|Yes| wait
  busy -->|No| start --> fill --> cont --> next

Not part of this design: a second lifecycle, a site-owned spec, an inbound MCP process server, a hosted computer, voice, X, or a tracker as the place stage progress is stored.

Risks to watch while building: a server-side clone of the repo can diverge from the engineer's tree; the site template can drift from the committed role file; a timeout from a pipeline must not be cached as a pass; two site projects for one product would split frontend and backend.

Mockups

Maya is the product manager for Expenses, which already exists inside Northwind Books. The left side is the product tree. The thread is Guide, a role she created. Checker and Builder are roles she added. They draft, check, and prepare. She accepts the feature and allows the one step. The chat is not the spec.

A product is a project: one repo, one sdd root. It is created with sdd init on that new repo and sdd greenfield for her sentence. Roles draft the vision, the requirements, the first features, and the architecture. She accepts each. sdd complete as her promotes memory/.

Inside a product, work is a backlog id. A feature uses the feature workflow: intent, design, tasks, implement, verify. An epic uses the enterprise-feature workflow: the feature, a high-level design, a low-level design, stories, tasks, then build. Both are ## F-NNN blocks. The screen labels them Feature and Epic. There is no second backlog.

Her path for one feature on Expenses:

1. She tells Guide, "I can never find last month's hotel charge."
2. Guide drafts a reading. Checker asks which month. She says the calendar month.
3. Guide says this is a feature, not an epic. She accepts. The site appends F-014 to memory/features.md as her.
4. Export is already the open change, and createChange would replace it, so F-014 stays planned. The chat says so. Guide can draft while it waits.
5. When no other change is active, the site runs sdd backlog start F-014 as her. Roles fill the feature workflow. Builder stops on one step. She allows it once. The site runs sdd next as her only when she continues.

The card inside the thread is still one decision. The same research applies: Amershi et al., CHI 2019, https://doi.org/10.1145/3290605.3300233 (G1, G4, G8, G9, G11, G16); Lee, Lee, and Mutlu, DIS 2024, https://doi.org/10.1145/3643834.3661576 (one card, once, at the decision); Muralidhar, Belloum, and Ashok, International Journal of Human-Computer Studies 204 (2025), article 103591, https://doi.org/10.1016/j.ijhcs.2025.103591 (a short layer first). The tree keeps the product, the feature, and the epic visible.

Agents

Five product managers reviewed this and accepted it. An agent is created for the organization as a template, then added to a product. The product file is what runs. Skills and connectors are later, and they are not on the create screen. The only permission on that screen is where the agent stops.

Maya opens Agents in Northwind Books and names Guide: one job, a description, and one stop. Save does not chat and does not add Guide to Expenses. She adds Guide to Expenses. The copy is the name, the job, the description, and the stop. If the template changes later, Expenses says the template was updated and she can update that copy or keep it. Opening Guide opens Guide’s own conversation.

flowchart TD
  org[Org agents]
  form[Name, job, description, one stop]
  save[Save template only]
  add[Add to one product]
  refuse[Name exists: write nothing]
  file[sdd role create writes the product role]
  chat[That agent's own conversation]
  org --> form --> save --> add
  add -->|name free| file --> chat
  add -->|name taken| refuse

Depends on

#37. Do not fold this epic into the search issues (#21–#26).