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/skills/design/references/09-publish.md
View on GitHub# Publish stage
Apply `{{provider:skills_root}}/design/patterns/metrics.md`; this stage's metrics unit is
`--stage publish`. First action, at Step 1: `stage start --stage publish`. Follow
the pattern's wait, check, and exit commands for everything after. When this
reference is used only as a correction recipe within another active stage,
retain that stage's metrics ownership.
Resume detection and stage tracking live in `{{provider:skills_root}}/design/SKILL.md`.
Publish updates the permanent docs. It runs once Review Gate (or Address
Feedback) has recorded an approved gate, and hands off to Completion
(`references/10-completion.md`) for archiving, tracker sync, and the final PR.
> โ ๏ธ Follow every step in order. Do not skip, summarize, or improvise. If you are unsure, ask before deviating.
> ๐ **Session continuity:** apply `{{provider:skills_root}}/design/patterns/session-continuity.md`.
## Step 1 โ Verify the gate is approved
`$DESIGN_DIR` comes from the router's Resume Detection. Read `design/Report.md`'s
`## Gate` section.
If `Approved:` is still `pending` or unset, tell the developer: "The design gate isn't approved yet โ run `{{provider:invoke:design}} review-gate {TICKET}` (or `{{provider:invoke:design}} address-feedback {TICKET}` if there are open concerns) first." Stop.
---
## Step 2 โ Doc impact identification
Before delegating, attempt yourself: `node docs/.og/cli.mjs search --term
<text>` (or `query --related-to <doc>`) against
`docs/.og/docs-operational-graph.sqlite` for docs related to this design
beyond what `design/Report.md` already names. Required (not best-effort):
when the graph is missing, stale (see `references/reindex-graph.md`'s Staleness check), or the call errors, fall back to grep/glob
over `{{DESIGN_DOCS_ROOT}}` for the same information โ either way, never let
this block the stage. This runs here, not inside the delegation below:
`{{DESIGN_ARCHITECT_AGENT}}` can resolve to a read-only agent with no shell
access (`@product-architect` on the Product track), so the query must be the
orchestrator's own step, with whatever it surfaces folded into the
delegation's context.
Delegate to `{{DESIGN_ARCHITECT_AGENT}}` (read-only โ no file writes):
- Read `design/Report.md` and the paths listed in its `selected_artifacts` state;
those paths point into the sibling `solution/` directory. Do not assume a fixed
set of solution filenames.
- Read `design/Report.md` WAF section (P1 items)
- Read the relevant docs under `{{DESIGN_DOCS_ROOT}}` for the subfolder(s) this design touches, plus whatever the graph query above surfaced
- Return: a list of specific `{{DESIGN_DOCS_ROOT}}` docs that need creating or updating, with the exact section and what settled decision to add or change โ no rationale, no rejected options, no open questions (Certainty principle)
- **Do not write or edit any files โ return output only**
This is an intelligent-approval checkpoint (`patterns/approval-intelligent.md`).
Auto-approval condition: every row names a specific doc, section, and change
with no judgment call about scope โ nothing ambiguous about what "settled
decision" it traces to.
Condition met โ note the list in one line and continue to Step 3 without
asking; the full list is still shown at Step 5's sign-off for the record.
A row is ambiguous (ties to no clear settled decision, or the scope is a
judgment call) โ this is a sign-off gate (`patterns/approval-sign-off.md`):
> "Here's what needs updating in `{{DESIGN_DOCS_ROOT}}`:
>
> - `{path}` โ `{section}`: <what to add or change>
>
> Confirm to proceed with updates? (**yes** / **adjust**)"
**Stop and wait.**
---
## Step 3 โ Apply doc updates
Read `{{DOC_PRINCIPLES_ARTICLE}}` before writing anything. For each destination,
also apply the matching Engineering Guide intent: `03 HLD Intent.md` for HLD
containers, `04 LLD Intent.md` for LLD component details, and `05 NFR Intent.md`
for NFR requirements and acceptance evidence. Tell `@docs-writer` which intent
applies to each path and require the resulting section to satisfy that intent.
Use `solution/Architecture.md` as the source for the complete published solution.
Port its settled decisions and end-to-end flows; treat the other selected solution
artifacts as supporting detail and flag any conflict before publishing.
Delegate to `@docs-writer` with the classified list from Step 2:
> "You are writing permanent documentation for design ticket {TICKET}. Read `{{DOC_PRINCIPLES_ARTICLE}}` before writing anything โ it contains destination rules, diagram standards, coloring requirements, and format priority.
>
> **Docs to create/update:**
> {list from {{DESIGN_ARCHITECT_AGENT}} โ path ยท section ยท diagrams_to_port (only when needed) ยท text_to_add}
>
> For each doc:
>
> 1. Read the current file if it exists
> 2. Port only the diagrams explicitly mapped for that destination from
> `solution/Architecture.md`; place a ported diagram before related prose.
> 3. Add a diagram only when the destination's applicable HLD/LLD/NFR intent or the
> mapped change requires one; do not manufacture diagrams for simple text updates.
> 4. All Mermaid diagrams MUST be colored (classDef + style directives)
> 5. Apply only settled decisions โ no rationale, rejected options, or open questions
> 6. If a new file is created or renamed, update `docs/README.md`
>
> Return a one-line summary per doc written."
Once `@docs-writer` completes, note the summary (one line per doc) and continue
straight to Step 4 โ the developer reviews it, with the architect's verdict,
at Step 5's single sign-off, not here.
For each doc written, call
`node docs/.og/cli.mjs index --dir . --doc <source-path> --edge <type> --to
<destination-path>` automatically โ edge direction is source-first, matching the
edge-type names: `<source-path>` is `solution/Architecture.md` (the Story's
settled solution), `<destination-path>` is the doc just written (the
HLD/Product-track file from Step 3's list above); `<type>` is `story-to-hld` for a
Project-track publish, `story-to-product` for a Product-track publish. `--to`'s
target must already be indexed (it errors otherwise); if the destination doc is
new, index it with a plain `index --doc <destination-path>` call first, then this
one. Non-blocking: on failure, report it in one line and continue โ never stop
the stage for this.
---
## Step 4 โ `{{DESIGN_ARCHITECT_AGENT}}` reviews doc changes
Apply the satellite review pattern (`{{provider:skills_root}}/design/patterns/satellite-review.md`). Delegate to `{{DESIGN_ARCHITECT_AGENT}}` to review the doc changes just made:
- Read the updated doc(s)
- Verify the changes are accurate, consistent with the rest of the docs, and don't introduce contradictions or gaps
- Verify the change stays at governance altitude and hasn't drifted into a downstream project's implementation detail
- **Do not write or edit any files โ return output only**
- Return: **OK** or a specific list of corrections needed
If **OK** โ proceed to Step 5.
If **corrections needed** โ apply the corrections, then show the developer what was changed (one line per edit) before re-delegating for one more review pass.
If still not OK after 2 iterations โ report to the developer and stop:
> "`{{DESIGN_ARCHITECT_AGENT}}` found unresolved issues with the doc update after 2 passes:
> <list of outstanding issues>
> Please review and resolve manually before continuing Publish."
---
## Step 5 โ Sign-off
Apply `patterns/phase-sign-off.md`. Present the doc-impact list from Step 2 and
what was written, and the architect's verdict from Step 4:
> "Permanent docs are updated and reviewed: {list from Step 2, `{{DESIGN_ARCHITECT_AGENT}}` OK}. Good to go, or what should change?"
`report`, then `wait start --reason approval --detail "Awaiting publish sign-off"`.
**Stop and wait.** On approval, record the acceptance check
(`--name "Publish sign-off"`, `--source developer`); without it `stage complete`
is refused.
Rework: apply the corrections, re-delegate to `{{DESIGN_ARCHITECT_AGENT}}` (Step 4), present again.
## Step 6 โ Report
Update `design/Report.md`:
- Phase tracker: `๐ฏ Context Gathering โ
ยท ๐ Ceremony โ
ยท ๐ Frame โ
ยท ๐ Research โ
ยท ๐ Evaluate โ
ยท ๐ฆ Solution โ
ยท ๐ Review โ
ยท ๐ฌ Address Feedback โ
ยท ๐ค Publish โ
ยท ๐ Completion ๐`
- Append to Efforts table: `| {YYYY-MM-DD} | Publish | MR approved by {approver}; docs updated: {list} |`
Then metrics `report`.
## Step 7 โ Commit
Propose:
> `docs({TICKET}): publish, update permanent docs`
This is a manual-operation sign-off (`patterns/approval-sign-off.md`) โ the
developer runs the commit, never you. `wait start --reason user_input`.
**Stop and wait.** On the reply, check `git log`/`git status`: the commit exists
and the worktree holds nothing from this phase. If not, say what is missing and
wait again. Then `stage complete --stage publish`.
๐ Re-read `{{provider:skills_root}}/design/SKILL.md` and resume the router from the next stage (Completion).
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: 472k | 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 |