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/Documentation/02 Structure.md
View on GitHub# Documentation Structure
_The four-tier model: what each tier is for and what lives where._
---
## Mental model
```
docs/
Target Architecture (HLD)/ ← WHY and WHAT we are designing toward
System Architecture (LLD)/ ← WHAT is currently built and HOW it works
Engineering Guide/ ← HOW to operate and develop
Stories/ ← Working folder (per-ticket, transient)
```
| Tier | Nature | Answers |
| ----------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------ |
| **Target Architecture (HLD)** | Aspirational — design intent | Why is the system designed this way? What are we building toward? |
| **System Architecture (LLD)** | Descriptive — current state | How does this actually work today? What are the component details? |
| **Engineering Guide** | Procedural — how to operate | How do I set up, deploy, debug? What are the team conventions? |
| **Stories** | Transient — delivery process | What did we decide, why, and what was built? (No length limit — archived after completion) |
Length budgets per tier live in `{{DOC_PRINCIPLES_ARTICLE}}`.
→ For how docs are produced and graduate to their permanent tier, see `Lifecycles/05 Documents Flow.md`.
→ For the certainty principle (HLD/LLD contain only settled outcomes), see `{{DOC_PRINCIPLES_ARTICLE}}`.
---
## Structure per tier
**Target Architecture (HLD):**
```
docs/Target Architecture (HLD)/
README.md ← router: "Active version: <v>" (see format below)
<Version>/
System Overview.md ← container list, data flows (Mermaid), tech stack
System Sizing.md ← capacity targets, scale assumptions, growth envelope
Containers/
<Name>.md ← one file per container (no numeric prefix)
Non-Functional Concerns/
<Concern>.md ← one file per WAF pillar, no combined Requirements.md
WAR/ ← audit snapshots, shared across versions
<Version>/
<YYYY-MM-DD>-<audit>.md
```
`README.md` format — router only, no content:
```markdown
# Target Architecture
**Active version:** [<Version>](./<Version>/System Overview.md)
| Version | Status | Notes |
| ------- | ---------- | ---------------------- |
| <v2> | Active | <one-line description> |
| <v1> | Superseded | <one-line description> |
```
No numeric prefixes inside a version. The four entries have fixed names — prefixes add noise without value. `System Sizing.md` is required, not optional.
**System Architecture (LLD):**
```
docs/System Architecture (LLD)/
README.md ← container folder index
<container>/
00. Overview.md ← responsibilities, key decisions
01. Data Flow.md ← sequence diagrams, integration patterns
...
where-we-are/ ← dated gap report snapshots
```
**LLD mirrors HLD.** Container names in LLD folders match HLD container names exactly. A gap between HLD containers and LLD folders is a delivery gap — by design, not an error.
**Engineering Guide:** numbered articles (`NN Title Case.md`). Operational and procedural content only — no architecture.
**Stories:** per-ticket working folders, archived after `{{SKILL_PREFIX}}dev document` completes. Not permanent reference docs.
---
## App README scope
A local dev quickstart only: what the app does, how to run it locally, links to HLD + LLD. If a README exceeds one page, something is in the wrong place — move it to `docs/`.
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 |