DataArt/artisyn-implementation-harness / skills/implementation-harness
implementation-harness
FlaggedInstall the portable AI-dev harness, rebuild its operational graph standalone, harvest project skill improvements into its canonical templates, package direct canonical edits into a portable bundle, or apply canonical updates to an existing project. Use /implementation-harness launch, /implementation-harness reindex-graph, or /implementation-harness patch harvest|prepare|apply.
canonical/docs/Engineering Guide/Lifecycles/05 Documents Flow.md
View on GitHub# Documents Flow
_How documentation is born, refined, and graduates to its permanent home._
---
## The pipeline
```mermaid
flowchart LR
T(["π« Ticket"]):::ticket
subgraph STORIES [" π Stories/<TICKET>/ β working directory (ticket context only) "]
direction TB
DESIGN["π¨ design/\n00 Frame Β· 01 Research\n02 Evaluate Β· Report.md"]:::design
SOL["π‘ solution/\nArchitecture Β· Design\nStack Β· Efforts"]:::solution
IMPL["π impl/\n0-intent.md Β· 1-plan.md Β· 2-report.md Β· stat.json"]:::impl
DESIGN --> SOL
end
subgraph PERMANENT [" ποΈ Permanent docs/ β project context (accumulates over time) "]
direction TB
PCTX["π§ {{PRODUCT_CONTEXT_DIR}}\nproduct-level docs"]:::pctx
HLD["πΊοΈ Target Architecture (HLD)\naspirational design intent"]:::hld
LLD["π§ System Architecture (LLD)\ncurrent implementation detail"]:::lld
EG["π Engineering Guide\noperational procedures"]:::eg
README["π apps/*/README.md\nlocal dev quickstart"]:::readme
end
T --> STORIES
SOL -->|"{{SKILL_PREFIX}}design publish (Product)"| PCTX
SOL -->|"{{SKILL_PREFIX}}design publish (Project)"| HLD
IMPL -->|"{{SKILL_PREFIX}}dev document\narch deviations"| HLD
IMPL -->|"{{SKILL_PREFIX}}dev document\ncomponent detail"| LLD
IMPL -->|"{{SKILL_PREFIX}}dev document\noperational steps"| EG
IMPL -->|"{{SKILL_PREFIX}}dev document\nenv vars Β· targets"| README
classDef ticket fill:#2C3E50,stroke:#1A252F,color:#fff
classDef impl fill:#1A6B3C,stroke:#14532d,color:#fff
classDef design fill:#8E44AD,stroke:#6C3483,color:#fff
classDef solution fill:#D97706,stroke:#B45309,color:#fff
classDef pctx fill:#7C3AED,stroke:#5B21B6,color:#fff
classDef hld fill:#1D4ED8,stroke:#1e3a8a,color:#fff
classDef lld fill:#0E7490,stroke:#0c4a6e,color:#fff
classDef eg fill:#065F46,stroke:#064e3b,color:#fff
classDef readme fill:#4B5563,stroke:#374151,color:#fff
```
> _Context sources: Research and Evaluate phases read existing docs as context before producing options β Product designs read `{{PRODUCT_CONTEXT_DIR}}/`, Project designs read `Target Architecture (HLD)/`. The track is resolved once in Frame (`patterns/context-resolution.md`) and recorded in `Report.md`'s `## Context` section. This read direction is not shown above to keep the pipeline readable._
---
## Graduation rules
| Lifecycle phase | Produces | Lives in | Mutability |
| -------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `{{SKILL_PREFIX}}dev context` | `0-intent.md` | `Stories/[TICKET] name/impl/` | Confirmed proto-spec β open questions may be appended |
| `{{SKILL_PREFIX}}dev plan` | `1-plan.md` | `Stories/[TICKET] name/impl/` | Immutable after approval |
| `{{SKILL_PREFIX}}dev context` | `2-report.md` (skeleton) | `Stories/[TICKET] name/impl/` | Living through the ticket |
| `{{SKILL_PREFIX}}dev implement` | Code commits | Codebase | β |
| `{{SKILL_PREFIX}}dev document` | LLD updates | `System Architecture (LLD)/` | Living |
| `{{SKILL_PREFIX}}dev document` | Engineering Guide entries | `Engineering Guide/` | Living |
| `{{SKILL_PREFIX}}dev document` | App README updates | `apps/*/README.md` | Living |
| `{{SKILL_PREFIX}}dev document` (deviation path) | Container or NFR updates within the active version | `Target Architecture (HLD)/<active>/Containers/` or `Non-Functional Concerns/` | Living |
| `{{SKILL_PREFIX}}design evaluate` | Recommendation + WAF assessment | `Stories/[TICKET] name/design/02 Evaluate.md` + `Report.md` | Immutable in Story |
| `{{SKILL_PREFIX}}design solution` | Certainty artifacts | `Stories/[TICKET] name/solution/` | Immutable after Publish gate |
| `{{SKILL_PREFIX}}design publish` (Product track) | Product architecture content | `{{PRODUCT_CONTEXT_DIR}}/<resolved subfolder>` | Living β accumulates over the product lifetime |
| `{{SKILL_PREFIX}}design publish` (Project track) | Updates reviewed by `{{DESIGN_ARCHITECT_AGENT}}` (max 2 passes) | `{{DESIGN_DOCS_ROOT}}<resolved subfolder>` | Living post-merge |
| `{{SKILL_PREFIX}}dev complete` (archive) | Full Story folder | `Stories/archive/` | Archived β no further edits |
| `{{SKILL_PREFIX}}where-we-are` Β· `{{SKILL_PREFIX}}war-*` | Architecture audit snapshots | `LLD/where-we-are/` or `HLD/WAR/<version>/` | Append-only β see Architecture Lifecycle invariants |
---
## Lifecycle of a doc
**Creation** β delivery docs are born in `Stories/[TICKET] name/` (ASCII folder names only) as working drafts. No doc goes directly to HLD, LLD, or the Engineering Guide without passing through a ticket.
**Graduation** β content graduates at two points: during `{{SKILL_PREFIX}}dev document` (implementation outcomes) and during `{{SKILL_PREFIX}}design publish` (design outcomes). Only settled outcomes graduate β rationale, comparisons, and open questions stay in the Story. Where an implementation change lands is decided by the tiers in `Documentation/02 Structure.md`; the Document stage records that decision per doc in the report's `## Documentation` table before `@docs-writer` writes anything. Design graduation is track-routed, resolved once in Frame and recorded in `Report.md`'s `## Context` section: Product lands in `{{PRODUCT_CONTEXT_DIR}}/`; Project lands in `Target Architecture (HLD)/`.
**Update** β permanent docs (HLD, LLD, Engineering Guide) are updated by subsequent tickets, not by reopening the original Story.
**Supersession** β HLD is versioned. Creating a new version is a human and business decision β the lifecycle never creates one automatically. When the team decides to cut a new version, the old version folder is kept as history and the README router is updated to point to the new active version. In-progress deviations always land in the current active version.
**Archival** β `{{SKILL_PREFIX}}dev complete` archives a story after doc consistency review, evidence-backed terminal resolutions in the single Review Findings ledger, and passing required acceptance/checks. The archived folder keeps its original ASCII name (`[TICKET] name`); done status lives in the report, not the folder name. Routine LLD lag is a doc-update task; deviation auditing compares implementation to HLD only. Archived stories are read-only references.
---
## What does NOT graduate
| Content type | Stays in |
| ---------------------------------- | ---------------------------------------------------- |
| Rationale, trade-offs | `Stories/[TICKET] name/design/02 Evaluate.md` |
| Rejected alternatives | `Stories/[TICKET] name/design/02 Evaluate.md` |
| Open questions | `Stories/[TICKET] name/design/02 Evaluate.md` |
| WAF assessment | `Stories/[TICKET] name/design/Report.md` WAF section |
| Implementation notes (2-report.md) | `Stories/[TICKET] name/impl/2-report.md` |
| Exploration drafts | `Stories/[TICKET] name/design/` |
## Harness improvement artifacts
Evolve reflections and candidate reports live in provider-local reflections/ and
evolve/ directories. Candidate evidence remains there; {{SKILL_PREFIX}}evolve adopt integrates
validated skills, agents and conventions into their recorded destinations. See
[the Evolve lifecycle](03%20Evolve%20Lifecycle.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why β repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" β or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself β your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |