---

Status: complete Last updated: 2026-04-30 Parent: Design - Architecture Overview Read before this: Design - Architecture Overview, Contract - Phase Outcome

Artifacts

Current state

Two categories, full stop:

1. Deliverables — synced to forge (or held in the local-fs adapter's durable storage). PREQ, SREQ, QA reports, dev journals, validation journals, test plan, simplify report, closeout artifacts (traceability matrix, learning report, MR description), Phase Outcomes.
2. Code and tests — travel via PR, never synced to issues separately. Forge-native PR↔issue linking handles discoverability.

There is no third "scratch" category. Apparent scratch artifacts collapse into one of two places:

• Inter-skill handoff content lives in Contract - Phase Outcome fields, not separate files.
• Things that serve a stakeholder are deliverables. The test plan is a manual test guide for the orchestrator. The simplify report records what changed for review.

The lens for any artifact: who consumes this? "The next skill, structurally" → Phase Outcome field. "A person or downstream process needs this content" → deliverable.

Storage

Skills write to .devwork/feature-X/ in the worktree. Whether the folder is gitignored depends on the active forge adapter:

• Remote-forge adapters (/tea-cli, /glab-cli, /gh-cli): .devwork/ is gitignored. Deliverables sync to the remote forge; the working folder is discarded with the worktree on cleanup. The issue tracker is the durable record.
• Local-fs adapter: .devwork/ is committed. The working folder is the durable record; it merges to main with the rest of the feature.

Same skill behavior in both cases — only the .gitignore line differs, set by the adapter at /setup.

Sync timing

Deliverables sync at phase completion (when the artifact is stable). Mid-phase mutations (a validate report being mutated by its companion fix skill) stay local until the phase is fully complete, then sync once.

For QA specifically: a "phase" is one /qa-fix invocation (typically 15 min to 1 hour). Reports sync to the issue when /qa-fix completes — or when /qa-validate completes if no fixes were needed. Each domain in the invocation gets its own comment. A later QA pass posts new comments for the domains it touched; we don't batch across runs.

Tiny illustrative snippets inside journal entries are fine — they're narrative, not canonical code.

Journal format

Dev journals and validation journals already follow a typed structure (STRUGGLE / DISCOVERY / $ISSUE_TYPE / COMPLETE) with consistent labeled fields. The migration plan is to add YAML frontmatter to each entry so the structured fields (type, tags, struggles, resolution status, duration) are machine-queryable for cross-feature learning analysis, while the long-form fields stay as readable prose.

Rationale

Two categories instead of three exist because the third category — "scratch" — never had a coherent definition. Every concrete example reduced to either a handoff (which is what Phase Outcomes are for) or a deliverable (which someone actually uses). Removing the category removes the temptation to put things in it that should be one of the other two.

Code travels only via PR because the PR is already the canonical artifact for code. Duplicating code into issue comments would create two sources of truth that drift. Tests are code, so the same logic applies — the test files live in the repo, the report describing what was tested lives in the issue.

Adapter-controlled .gitignore resolves an old tension. For projects with a remote forge, .devwork/ should be gitignored — the remote is the durable record, the working folder is ephemeral. For local-only projects, .devwork/ should be committed — there is no remote, the working folder is the record. Letting the adapter set this at /setup time means skills don't have to know which mode they're in.

Sync-on-phase-completion (rather than continuous sync) avoids the "partially-formed artifact in the issue" failure mode. A validate report being mutated by fix is normal mid-phase state but confusing if seen partway through. Wait until the phase finishes, then post once.

Open questions

• The journal frontmatter schema isn't finalised. Initial sketch in Forgejo issue #1.
• The producer/consumer path drift on dev journals (develop/SKILL.md writes dev-journal-WU-N.md at feature root; learning-analysis and simplify-report look at sreqs/SR-*/dev-journal.md) is tracked as Forgejo issue #3.