diff --git a/.agents/skills/archie-docs-and-writing/SKILL.md b/.agents/skills/archie-docs-and-writing/SKILL.md index 18cbf7360..b16cf752c 100644 --- a/.agents/skills/archie-docs-and-writing/SKILL.md +++ b/.agents/skills/archie-docs-and-writing/SKILL.md @@ -67,6 +67,7 @@ The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-09-18. | Content | Destination | |---|---| | Cross-cutting approved architecture index | `docs/prds/01-project-management.md` | +| New capability with no settled design yet (CLAUDE.md's "write a decisive doc before coding") | New `docs/prds/.md` — use the PRD template in `references/templates.md`, which folds in a multi-agent execution breakdown so the sub-issues can be picked up without re-deriving the design | | Focused domain or requirement decision | Matching `docs/architecture/*.md` file | | Unresolved migration question | `docs/architecture/migration-decisions.md` | | Contributor protocol that must load before work | `CLAUDE.md` | diff --git a/.agents/skills/archie-docs-and-writing/references/templates.md b/.agents/skills/archie-docs-and-writing/references/templates.md index c8099d50d..d7bf57b15 100644 --- a/.agents/skills/archie-docs-and-writing/references/templates.md +++ b/.agents/skills/archie-docs-and-writing/references/templates.md @@ -11,6 +11,7 @@ sections. Keep facts, decisions, and open questions visibly separate. - [Feature ownership and deprecation record](#feature-ownership-and-deprecation-record) - [Operational runbook](#operational-runbook) - [Documentation change review](#documentation-change-review) +- [PRD: open capability design with multi-agent execution](#prd-open-capability-design-with-multi-agent-execution) ## Architecture decision record @@ -362,3 +363,123 @@ Observed: ```` + +## PRD: open capability design with multi-agent execution + +For `docs/prds/*.md` — CLAUDE.md's "no settled design exists" doc. The point +of this template is that a cheaper/faster model can implement straight from +it without re-deriving architecture: every decision the epic left open gets +made here, not deferred again, and every file an implementer touches is +named before any bead is picked up. `docs/prds/image-capability-contract.md` +is the worked example this template was extracted from — read it once for +the shape before writing a new PRD from a blank page. + +The three failure modes this template exists to prevent: + +- **Deferred decisions posing as scope.** "Hosted provider implementation is + a separate bead" is not a design decision, it's a missing one. If an open + question blocks an implementer, decide it here, in the PRD — not "this bead + will decide it later," which is how the same question gets re-opened by + every bead that touches it. +- **Assumed gaps.** Before writing a section for "what's missing," grep for + it. `image-capability-contract.md`'s delivery section exists mostly because + the pipeline it needed already shipped for video — the section reports + that, instead of specifying new plumbing nothing required. +- **Task lists a model can't execute standalone.** A subtask is not "wire the + delivery path"; it's the file, the interface it must satisfy, and the + existing call site that already proves the pattern (`internal/tools/minimax/tool.go`, + not "a tool like the video one"). + +````markdown +# capability design + +Epic: `` / GitHub `#` (""). + + + +## Problem + + + +## Design + + + +## (`#`) + +One section per sibling bead the epic lists as separate scope. Each one: + +- **Decision, not a deferral.** If the epic or a prior doc left this open, + decide it here and say why in one paragraph, citing what's actually in + the tree (a similar client already in the codebase, an existing config + convention, an interface already proven by another feature). "Decide and + record which at that bead's own design-doc step" is the sentence this + template exists to stop someone from writing twice. +- **Call site**, named exactly: ``, the function/type it adds + or extends, and the existing analogous call site it follows (never "a + handler like the others" — name the actual one). +- **Reuse check.** Grep before specifying new plumbing. State what already + exists and what's actually new, the way a delivery pipeline already + proven by one media type doesn't need re-inventing for a second. +- **Error/failure mapping**, as a table, when the sub-feature crosses a + provider/backend boundary: condition → contract error, so an implementer + never invents a new sentinel mid-way through. +- **Testing.** What's fakeable vs. what needs a real backend, and which + gate (`task check` vs. a documented manual smoke command) each belongs to. + +## Call site inventory + +| concern | file | change | +|---|---|---| +| | `` | done (`#`) / new (`#`) / none — already handles this | + +Every file any sub-feature touches, old or new, in one table — so an +implementer greps this instead of re-deriving it, and a reviewer can tell +at a glance whether a PR touched something the design didn't name. + +## Execution: multi-agent team breakdown + +One row per sub-feature section above. This is what turns the design into +something a `/council`-style review or a cheaper/faster implementer model +can run against directly instead of needing the full design re-explained. + +| sub-feature | issue | implementer scope | suggested council lenses | why | +|---|---|---|---|---| +| | `#` | | `lens-`, `lens-` | | + +Pick lenses from the five in `.claude/workflows/council.js` +(`boundary`, `contract`, `deletionist`, `operator`, `maintainer`) by what the +slice actually risks getting wrong, not all five by default — a +generate-and-poll HTTP client mostly risks failure-mode gaps +(`lens-operator`), not domain-boundary violations. Run `/council` with +`--lenses ` once the implementation is gate-clean, before opening +the PR for human review, same as any other open-decision residue at the +end of a session. + +An implementer working one row needs only: this doc's matching sub-feature +section, the call-site inventory, and the linked issue's acceptance +criteria. It should not need the rest of the epic's history — that's the +signal the PRD is thorough enough to hand to a faster/cheaper model. + +## File and link the beads + +For each sub-feature issue already filed against the epic (or newly filed +if the epic didn't pre-file its sub-issues): + +- Issue body links back to this doc's matching section by heading, not by + restating the design — `bd update --description` and, if the issue + also lives on the forge, keep both current (check whether this repo's + sync command actually propagates a description edit before trusting it + updated both; direct edit on both sides is the fallback). +- Issue keeps its own acceptance criteria as the authoritative "done" + check — the PRD section is how, the issue's criteria are whether. +- Add the suggested lenses from the Execution table as a line on the issue + itself, so picking it up needs no round-trip back to this doc to know + which `/council` lenses to run before it's done. +```` diff --git a/docs/prds/image-capability-contract.md b/docs/prds/image-capability-contract.md index 9e450a855..08ee57eb1 100644 --- a/docs/prds/image-capability-contract.md +++ b/docs/prds/image-capability-contract.md @@ -455,3 +455,33 @@ grep: | Telegram delivery | `internal/channels/telegram/media.go` | none — already handles `"image"` | | Dashboard delivery | `internal/webui/api_chat.go` | none in this epic — tracked separately (archie-core-1786748942243-6-f109697e) | | docs | `docs/` user-facing guide (#502) | new, against this design | + +## Execution: multi-agent team breakdown + +Each row is independently implementable from its own section above plus the +call-site inventory — an implementer does not need this whole document +re-explained, only its row. Lenses are picked from +`.claude/workflows/council.js` (`boundary`, `contract`, `deletionist`, +`operator`, `maintainer`) by what each slice actually risks getting wrong, +not all five by default. + +| sub-feature | issue | implementer scope (call-site rows) | suggested lenses | why | +|---|---|---|---|---| +| Hosted provider | #498 | `internal/infrastructure/image/openai/*.go` (generate via ai-sdk, edit via direct HTTP client) | `lens-contract`, `lens-operator` | contract: the error-mapping table must actually produce the sentinels it claims, not leak ai-sdk/HTTP errors raw; operator: a live paid API's rate-limit/timeout/auth-failure paths are exactly the 3am-unattended-host case this lens exists for | +| Local GPU provider | #499 | `internal/infrastructure/image/comfyui/*.go` (submit/poll against ComfyUI) | `lens-operator`, `lens-deletionist` | operator: backend-down, workflow-missing, and stuck-job failure modes on a host the operator's GPU actually runs; deletionist: a second, unevidenced "recipe" added later without real-hardware proof is exactly the speculative scaffolding this lens rejects | +| `/image` routing | #500 | `internal/domain/messaging/commands.go`, `internal/gateway/gateway.go` (`Router.Images`, `handleImage`) | `lens-boundary`, `lens-maintainer` | boundary: a new `Router` field and its dependency on `image.Registry` must respect the same layering `Models`/`Tasks`/`Controller` already do; maintainer: this is the first local command with an explicit ask-once clarification exchange, not a single-shot reply — legibility for the next person who adds a command matters here | +| Delivery + autonomous tool | #501 | `internal/tools/image/tool.go`, `internal/app/archied/bootstrap.go` (`registerImageTool`) | `lens-deletionist`, `lens-contract` | deletionist: the whole point of this section is "reuse `generate_video`'s pipeline, do not rebuild it" — this lens is the check that the implementation actually did that; contract: the new tool's `MultimodalResult`/`MediaRef{Type: "image"}` output must match the shape `multimodalMediaRefs` already decodes, not a near-miss | + +Run `/council --lenses ` once a row's implementation is gate-clean +(`task check` passing), before opening its PR — same timing as any other +open-decision residue at the end of a session, not a standing per-commit +gate. + +## File and link the beads + +`#498`–`#501` already exist (bd `archie-core-1786748942169-3-ae7cfaea`, +`…-219-5-9844a72e`, `…-193-4-5072b564`, `…-243-6-f109697e`), filed under +epic #496 before this document's decisions were made. Each one's +description now links back to its matching section above instead of +restating it, and carries its row from the Execution table above so picking +it up needs no round-trip back to this document.