feat(internal-artifacts): persist specs/plans/reports to gitignored .internal/ #6
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/internal-artifacts"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Move user-written specs, architect plans, and reviewer reports into a gitignored
.internal/directory at the repo root. The orchestrator becomes the sole writer (subagents retainedit: deny). Existing trackedspec_installer.mdandspec_memory.mdmove out of the index;PLAN_installer.mdmoves into.internal/plans/. Workflow prose for the 7 orchestrator flows gains explicit "Persist …" sub-steps.Why
Specs, plans, and reviewer reports are working artifacts — they help the orchestrator's iterations but don't belong in the public bundle. Pushing them to Forgejo exposes internal design decisions and review trails that the user wants kept local. This branch makes the convention a first-class artifact of the workflow.
What ships
Modified
workspace/opencode/agents/orchestrator.md— frontmatteredit: ask→edit: allow; new "Persistence discipline" section; per-flow "Persist …" sub-steps for all 7 flows (sub-step suffixes4a,5a, etc. — no renumbering).workspace/opencode/agents/architect.md,code-analyzer.md,security-auditor.md,arch-quality-reviewer.md— each gains a one-line "Output persistence" note pointing at.internal/..gitignore—PLAN_installer.mdentry replaced with.internal/.AGENTS.md— 3 stalespec.mdreferences dropped; new §5.8 "Internal artifacts (.internal/)" documents the convention.README.md— stalespec.mdtree entry dropped.CHANGELOG.md—[Unreleased]block updated with the convention.Removed (from tracked tree)
spec_installer.md→.internal/specs/installer.mdspec_memory.md→.internal/specs/memory.mdNew
.internal/(gitignored) withspecs/,plans/,reports/subdirs.workspace/opencode/tests/test_internal.sh— structural validator. 8 assertions:.gitignoreentry, orchestratoredit: allow, every flow references.internal/, no stalespec.mdin shipped docs, every reporting agent has Output persistence note, files relocated, files removed from index, git status clean for the affected paths.Design decisions resolved
editpermission (askvsallowvs per-path allowlist)edit: allowcode-implementer.md:84precedent. Per-path allowlists are NOT supported by opencode's schema (same constraint aswebfetchatagents/architect.md:95)..internal/plans/<slug>.json(raw Mode B output) +.internal/plans/<slug>.md(orchestrator-generated Markdown wrapper)<slug>git rm --cached(notgit rm) preserves the file until the explicitmv, in case the move fails mid-flight.Verification
Compatibility
bash workspace/opencode/install.shusers: no change (the installer does not create or read.internal/)./feature <description>invocations: persist artifacts to.internal/automatically; the user still sees the chat-thread summary; the persistence is for traceability./review,/audit,/explain,/onboard,/update,/status,/next,/continue) bypass the orchestrator and haveedit: denyon their agent; they remain chat-only outputs. Out of scope for this branch.Out of scope
.internal/entries" — the user owns their.internal/directory.spec_installer.mdandspec_memory.mdmove verbatim.How to review
Commits
- .gitignore: replace PLAN_installer.md entry with .internal/ (directory-level ignore subsumes the legacy one-off plan ignore). - README.md: drop the stale 'spec.md' tree entry. - AGENTS.md: drop 3 stale 'spec.md' references; add new §5.8 'Internal artifacts (.internal/)' documenting the convention. - CHANGELOG.md: add [Unreleased] entries under ### Added and ### Changed documenting the new convention, the orchestrator frontmatter change, the agent note additions, and the spec_*.md removal. - git rm --cached spec_installer.md spec_memory.md + mv to .internal/specs/. - mv PLAN_installer.md (untracked) to .internal/plans/installer.md. After this commit: - spec_*.md no longer exists in the repo root or in the index. - .internal/{specs,plans,reports}/ are gitignored. - spec.md references in shipped docs are gone (4 references dropped).The orchestrator becomes the sole writer to the gitignored .internal/ directory. Subagents (analyzer, architect, security-auditor, arch-quality-reviewer, code-implementer, codegraph) all retain edit: deny and return content in their output; the orchestrator persists it. Changes: - agents/orchestrator.md frontmatter: edit: ask → edit: allow (matches the code-implementer precedent; the orchestrator is gated by user approvals at every flow gate, not by per-edit dialogs. Object-form per-path edit allowlists are not supported by opencode's schema, same constraint as webfetch documented at agents/architect.md:95). - agents/orchestrator.md body: new 'Persistence discipline' section names the four .internal/ destinations and the read-only pre-existing-artifact lookup convention. Each of the 7 flows (/init, /feature, /bugfix, /code-review, /deep-analyze, /security-scan, /implement) gains explicit 'Persist …' sub-steps using sub-step suffixes (4a, 5a, 5b, 6a, 10a) to keep the diff additive. - agents/architect.md, code-analyzer.md, security-auditor.md, arch-quality-reviewer.md: each gains a one-line 'Output persistence' note in the body, after the closing ``` of the output template. No frontmatter change; edit: deny preserved. - tests/test_internal.sh: new structural validator. 8 assertions check the convention end-to-end: .gitignore entry, orchestrator edit: allow, every flow references .internal/, no stale spec.md in shipped docs, every reporting agent has the Output persistence note, files relocated, files removed from the index, git status clean for the affected paths. Naming: <slug> matches the kebab-case regex ^[a-z0-9]+(-[a-z0-9]+)*$. <flow> in {init, feature, bugfix, code-review, deep-analyze, security-scan, implement}. <role> in {diff-context, analyzer, architect, security, arch}.