archgen-skill 0.0.2 → 0.0.4

package/vendor/skills/archgen/references/mcp-and-skills.md

@@ -4,43 +4,114 @@
 
 1. **Identify** the platform (SKILL.md Step 0), load its row from
    references/platforms.md section MCP: config file, top-level key, quirks.
-2. **Prefer the platform CLI** where the table lists one. It handles scope and
-   file selection correctly:
+2. **Discover** — when the correct installation method or config shape for
+   the detected harness is not confidently known, web-search the CURRENT
+   official installation docs/command FIRST. Never trust potentially-stale
+   memorized commands or invented config shapes; uncertainty triggers search,
+   not guessing.
+3. **Scope** — choose and state the install scope explicitly:
+   - **GLOBAL** — server types that are global entries (npx/npm-based MCP
+     servers usable across harnesses). Recommended for universally-useful
+     servers (codegraph is the canonical example) unless the user prefers
+     project-local.
+   - **HARNESS-SPECIFIC** — write into the detected platform's config only.
+     Recommended when the server only matters to that platform.
+   The user's approval covers the stated scope.
+4. **Prefer the platform CLI** where the table lists one, passing the scope
+   flag that matches the chosen scope:
    - `claude mcp add --scope project --transport http <name> <url>`
    - `codex mcp add <name> --url <url>` or `codex mcp add <n> -- cmd args`
    - `gemini mcp add -s project -t http <name> <url>`
-3. No CLI available: draft the exact config diff against the platform's real
+5. No CLI available: draft the exact config diff against the platform's real
    shape (see assets/mcp-template.json for annotated canonical forms) and SHOW
    it to the user. **USER APPROVAL GATE** — wait for an explicit yes before any
    write; approval is never inferred from earlier steps.
-4. Apply, then apply the restart semantics from the platforms table.
-5. Verify the tool is visible after reload; report failure modes honestly.
+6. Apply, then apply the restart semantics from the platforms table.
+7. Verify the tool is visible after reload; report failure modes honestly.
 
 Never write MCP configs silently. Never invent config shapes — the four known
 top-level keys are mcpServers / servers / mcp / context_servers; remote URL
-fields vary (url vs serverUrl vs httpUrl) per the platforms table.
+fields vary (url vs serverUrl vs httpUrl) per the platforms table. Uncertainty
+triggers web-search of current official docs, never invention.
 
 ## FETCH-SKILL procedure
 
-1. Read assets/skill-registry.json. Match the current task domain against
-   entry `matches` patterns (e.g. frontend/UI work matches ui-skills).
-2. Install into the CURRENT platform's skill dir (platforms.md paths):
-   - Generic: `npx skills add <owner>/<repo>` (writes correct path for 75+
-     harnesses; `-g` for global).
-   - Entry-specific command when present (e.g. `npx ui-skills get baseline-ui`).
-3. Confirm files landed where expected; then FOLLOW the fetched skill's own
-   instructions for the task domain.
-4. Missing capability: web-search reputable skill repos, propose to user,
-   on approval append an entry to the registry (PR or local edit).
+Capability-skill loading is **REQUIRED, not opportunistic**. Whenever planned
+work touches a registry `matches` domain, the matching skill MUST be loaded —
+during planning (GENERATE / BROWNFIELD / UPDATE) AND re-verified during
+execution (worker dispatch). UI/design/frontend/animation/component/
+landing-page work REQUIRES the design skills (`ui-skills`, `policy:
+"required"`) loaded first. Referenced from elsewhere as:
+*see references/mcp-and-skills.md § FETCH-SKILL procedure*.
+
+0. **WHEN** — mandatory, twice per matched task:
+   - **Pre-planning scan**: while planning, check every task's title, summary,
+     and `file_ownership` against the registry BEFORE the plan is finalized;
+     fetch any matched skill at that point.
+   - **Pre-dispatch verification**: immediately before dispatching each worker,
+     re-verify its match; if the skill is missing from the platform skill dir,
+     install it before dispatch proceeds.
+1. **MATCH** — read assets/skill-registry.json. Test every task's title,
+   summary, and file_ownership globs against each entry's `matches` patterns
+   using case-insensitive substring matching (e.g. a task titled "polish
+   landing page hero" matches ui-skills via `"landing page"`). One hit = this
+   procedure is mandatory for that task.
+2. **RESOLVE** — determine the CURRENT platform's skill dir from
+   references/platforms.md § Skill install paths. That table owns the paths;
+   never duplicate them here.
+3. **INSTALL once if absent** — cached check first: if the skill is already
+   present in the resolved platform skill dir, skip reinstall and go to step 4.
+   Otherwise run the entry's `install` command (generic fallback:
+   `npx skills add <owner>/<repo>`; `-g` for global; entry-specific commands
+   like `npx ui-skills get baseline-ui` when present). Then VERIFY presence:
+   confirm the skill directory/SKILL.md landed where platforms.md says it
+   should. Fetch happens ONCE per project; later runs are cache hits.
+4. **INTEGRATE** — inject the follow-instruction into (a) the planning context
+   so tasks reference the skill's standards, and (b) EVERY affected worker
+   prompt, using this sentence template:
+
+   > `<Domain> work: follow <skill-dir>/SKILL.md (installed via FETCH-SKILL) — apply its standards to every relevant decision.`
+
+   Concrete design instantiation for ui-skills:
+
+   > `Design work: follow <skill-dir>/SKILL.md (installed via FETCH-SKILL) — apply its component/motion/baseline standards to every visual decision.`
+
+5. **AUDIT** — workers MUST state in their completion report whether they
+   followed the injected skill, one auditable line, e.g.:
+   `Skill compliance: followed ui-skills (<skill-dir>/SKILL.md)` or
+   `Skill compliance: NOT followed — <reason>`.
+6. **MISSING CAPABILITY** — unmatched-but-obvious domain (user says "make it
+   pretty" with no registry entry): web-search reputable skill repos, propose
+   to user, on approval append an entry to the registry (PR or local edit).
+   Never add registry entries without explicit user approval.
 
 ## Registry entry shape
 
+Canonical keys, in order — there are no others. Notably there is NO
+`npxCommand` field anywhere in the registry; the executable command lives in
+`install` (with optional `direct_fetch`):
+
 ```json
 {
   "name": "short-name",
   "purpose": "when to reach for it",
   "repo": "owner/repo",
   "install": "npx skills add owner/repo",
-  "matches": ["frontend", "ui", "design"]
+  "direct_fetch": "optional per-skill fetch command",
+  "browse": "optional listing command",
+  "mcp_endpoint": "optional MCP URL",
+  "matches": ["frontend", "ui", "design"],
+  "policy": "required"
 }
 ```
+
+- `matches[]`: case-insensitive substrings tested against task titles,
+  summaries, and file_ownership during the FETCH-SKILL domain scan (step 1).
+- `policy` (`required` | `on-demand`) — how mandatory loading is:
+  - `"required"`: loading is MANDATORY whenever work touches any of the
+    entry's `matches` domains — pre-planning fetch plus pre-dispatch
+    verification (FETCH-SKILL steps 0–5 all apply). Currently only ui-skills
+    carries this; design/UI/frontend work must not proceed without it.
+  - `"on-demand"`: fetched only when a task explicitly names the installer or
+    another registry entry lacks a usable command (e.g.
+    vercel-skills-installer).

package/vendor/skills/archgen/references/orchestration.md

@@ -39,9 +39,63 @@ Dispatch AFTER artifacts exist and validate.mjs passes. The verifier:
 Orchestrator fixes issues (edits artifacts) and re-dispatches. Loop until
 APPROVE — never present to the user before verifier approval.
 
+## §plan-review — post-plan review stage
+
+Run AFTER verify-plan returns APPROVE and BEFORE the user gate. Dispatch one
+or more REVIEWER sub-agents; count scales with the right-sizing class:
+
+- SMALL: main-agent self-review acceptable if no reviewer mechanism exists.
+- MEDIUM: 1 reviewer.
+- LARGE: 2–3 reviewers split by concern (correctness / ordering / docs).
+
+```
+TASK: Review the plan in .archgen/<slug>/ READ-ONLY.
+EXAMINE:
+  - edge cases per module
+  - task ordering / parallelization sanity (waves vs real dependencies)
+  - cross-module contract mismatches (interfaces, paths, naming)
+  - enhancement recommendations
+  - documentation completeness
+DELIVERABLE: numbered findings list; each finding = what + where + why.
+You NEVER edit files. Report only.
+```
+
+Reviewers are read-only and report-only — they never edit artifacts or code.
+The orchestrator fixes the artifacts itself, re-runs validate.mjs + re-dispatches
+the verifier gate after every change, and loops until zero findings remain or
+findings are explicitly waived by the user.
+
+## §investigate — root-cause protocol
+
+Triggered when the USER reports repetitive/recurring issues AFTER implementation
+waves completed. Do NOT patch-fix under this protocol. Complexity-sized dispatch:
+
+- SMALL scope: main agent investigates directly.
+- MEDIUM/LARGE: 1–3 investigator sub-agents split by suspected subsystem.
+
+Investigators produce ALL four:
+
+1. Root cause statement — one sentence naming the actual defect.
+2. Evidence — files/lines/repro steps.
+3. Blast radius — which tasks/artifacts are affected.
+4. Remediation plan — routed through the normal gates: new fix tasks get fresh
+   ids inheriting the affected task's ownership globs.
+
+Token discipline: investigators read narrowly around evidence, not whole-repo
+sweeps. Patch-fixes without a root-cause statement are forbidden under this
+protocol.
+
 ## §dispatch — wave execution
 
-### Tier 1: native sub-agents (preferred where strong)
+Dispatch policy: dispatch each task to the harness's NATIVE sub-agent mechanism
+when available AND functional. If sub-agents do not exist on this platform, or
+the sub-agent fails, or lacks required tool permissions (read/write/etc.), the
+MAIN AGENT executes the task ITSELF — sequentially, respecting waves and
+ownership globs. Cross-harness/platform delegation is allowed ONLY through an
+explicit user gate (below). There is NO automatic fallback to other harnesses,
+platforms, or CLIs — ever.
+
+### Native sub-agents (preferred)
 
 - Claude Code: background Agent tool per task; add worktree isolation for
   tasks whose ownership might brush shared files.
@@ -51,55 +105,64 @@ APPROVE — never present to the user before verifier approval.
 - Gemini CLI: parallel @agents are hub-and-spoke only AND have no isolation →
   use them ONLY for read-only/research waves unless wrapping in worktrees.
 
-### Tier 2: bash fallback workers (universal floor)
+### When sub-agents are unavailable or fail
 
-```bash
-#!/usr/bin/env bash
-set -uo pipefail
-SLUG="<slug>"; ROOT="$(pwd)"; SKILL="<abs-path-to-skills/archgen>"
-run_task() { # $1=id  $2=prompt-file
-  local id="$1" pf="$2" log=".archgen/$SLUG/results/$id.log"
-  mkdir -p "$(dirname "$log")"
-  local body; body="$(cat "$pf")
-
-You own exactly the file_ownership globs listed for this task in tasks.yaml. Follow archgen code-standards. On success run: node \"$SKILL/scripts/set-status.mjs\" .archgen/$SLUG/tasks.yaml \"$id\" done ; on failure set-status failed."
-  case "$ARCHGEN_HARNESS" in
-    claude)    claude -p "$body" --output-format json --permission-mode acceptEdits > "$log" 2>&1 ;;
-    opencode)  opencode run "$body" --auto --format json > "$log" 2>&1 ;;
-    codex)     codex exec --sandbox workspace-write --json -o "$log.final" "$body" > "$log" 2>&1 ;;
-    gemini)    gemini --output-format json "$body" > "$log" 2>&1 ;;
-    agy)       agy -p --output-format json --print-timeout 15m "$body" > "$log" 2>&1 ;;
-    *) echo "unknown harness: $ARCHGEN_HARNESS" >&2; return 9 ;;
-  esac
-
-You own exactly: $(node "$SKILL/scripts/impact.mjs" .archgen/$SLUG/tasks.yaml "$id" >/dev/null 2>&1 && echo 'see tasks.yaml file_ownership'). Follow archgen code-standards. On success run: node "$SKILL/scripts/set-status.mjs" .archgen/$SLUG/tasks.yaml "$id" done ; on failure set-status failed." \
-}
-# Wave N: launch all frontier tasks in parallel…
-for t in $(node "$SKILL/scripts/next-tasks.mjs" .archgen/$SLUG/tasks.yaml \
-           | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>console.log(JSON.parse(d).waves[0].map(t=>t.id).join(" ")))'); do
-  run_task "$t" ".archgen/$SLUG/results/$t.prompt" & pids="$pids $!"
-done
-fail=0; for p in $pids; do wait "$p" || fail=1; done
-exit $fail   # orchestrator inspects statuses before next wave
-```
+Detect first — one of:
+
+- mechanism missing on this platform;
+- spawn failure (sub-agent never started / crashed at launch);
+- tool-permission gaps (sub-agent runs but cannot read/write/edit files).
+
+Then, in order:
 
-Isolation upgrade for Tier 2 when ownership borders are tight:
+1. DEFAULT — main agent executes the task itself, sequentially, respecting
+   waves and file_ownership globs. No user permission needed for this.
+2. USER GATE — cross-harness/platform delegation ONLY. When the sub-agent
+   problem looks platform-specific, STOP and tell the user the concrete issue,
+   propose using another platform/harness for that specific task (name the
+   harness + its command shape), and proceed ONLY after the user explicitly
+   allows it. Log the user's choice in the final report.
+
+Never silently switch harnesses. Never ask permission to fall back for routine
+failures the main agent can simply do itself.
+
+A sub-agent MECHANISM failure (missing/spawn/permissions) is not a TASK
+failure — run the diagnose-and-ask flow above first. Mark a task failed only
+after execution was actually attempted (by sub-agent or main agent) and did
+not complete.
+
+Isolation for native sub-agents when ownership borders are tight:
 
 ```bash
 git worktree add ".worktrees/$id" -b "task-$id"
-# run worker with cwd=.worktrees/$id, then merge task-$id on success
+# point the sub-agent's cwd at .worktrees/$id, then merge task-$id on success
 ```
 
-### Worker prompt contract (both tiers)
+### Worker prompt contract
+
+Every worker receives ALL of:
+
+- task id + title;
+- its acceptance criteria VERBATIM;
+- its file_ownership globs ("edit NOTHING outside these");
+- the code-standards reference (`references/code-standards.md`);
+- instruction to run set-status done/failed immediately upon finishing:
+  `node <skill>/scripts/set-status.mjs .archgen/<slug>/tasks.yaml <id> done|failed`;
+- commit guidance: commit completed work scoped to the owned files;
+- BEFORE writing code run
+  `node <skill>/scripts/plan-graph.mjs --node <task-id> --tasks <tasks.yaml>`
+  and honor every connected dependency shown;
+- all file paths come from tasks.yaml/architecture.yaml VERBATIM — never
+  reconstruct paths from memory.
 
-Every worker receives: task id+title, its acceptance criteria verbatim, its
-file_ownership globs ("edit NOTHING outside these"), the code-standards
-reference, and the done/failed status-update command. Workers do NOT talk to
-each other; coordination happens only through tasks.yaml state.
+Workers do NOT talk to each other; coordination happens only through
+tasks.yaml state.
 
 ## Failure policy
 
-- Worker exit ≠ 0 OR status=failed → leave it failed. NEVER auto-retry.
+- Sub-agent mechanism failure (missing/spawn/permissions) → §dispatch
+  diagnose-and-ask flow FIRST. It is not yet a task failure.
+- Task exit ≠ 0 OR status=failed → leave it failed. NEVER auto-retry.
 - Downstream tasks stay blocked by the resolver (blockedByFailure).
 - Report to user: failed id, log path, proposed fix-task description.
   [wait for user] A fix task gets fresh id, depends_on=[], ownership of the

package/vendor/skills/archgen/references/platforms.md

@@ -23,6 +23,23 @@ confirmed. The orchestrator loads ONLY the row matching Step-0 detection.
 Universal fallback: `.agents/skills/` project + `~/.agents/skills/` user works
 across most harnesses. Primary distribution: `npx skills add <repo>` (75+ agents).
 
+## archgen installed layout
+
+`install.sh` / `npx archgen-skill install` maintain ONE canonical store plus
+thin bridges — the skill is never copied twice:
+
+| Path | Role |
+|---|---|
+| `.agents/skills/archgen/` | Canonical store — `SKILL.md`, `scripts/`, `references/`, `assets/` |
+| `.claude/skills/archgen` | Optional symlink → canonical store, for Claude Code discovery |
+| `CLAUDE.md` | One-line `@AGENTS.md` bridge only — no content of its own |
+| `AGENTS.md` | The hub every harness reads; hosts the features registry between `<!-- archgen:features:start -->` and `<!-- archgen:features:end -->` |
+
+The registry table (`| Feature | Status | Updated |`, one row per
+`.archgen/<slug>/`) is machine-maintained by `scripts/update-agents.mjs` after
+every generate/plan/wave run — never hand-edit it; edit `.archgen/` state and
+re-run the script instead.
+
 ## MCP configuration
 
 Four different top-level keys exist — NEVER assume `mcpServers`:
@@ -52,24 +69,11 @@ Claude Code project-scope servers.
 |---|---|---|---|
 | Claude Code | `Agent` tool + subagent_type; `.claude/agents/*.md` | Yes (default since v2.1.198; cap ~20) | BEST: `isolation: worktree` frontmatter; `/batch` |
 | OpenCode | task/subagent tool + subagent_type | Yes (fg + background) | None in core → use file-ownership discipline or team-mode plugin worktrees |
-| Codex CLI | model-mediated `spawn_agent`; max_depth=1 | Yes but children can't nest | None → prefer top-level parallel `codex exec` + manual git worktrees |
+| Codex CLI | model-mediated `spawn_agent`; max_depth=1 | Yes but children can't nest | None built-in → flatten plans into top-level `spawn_agent` calls (children cannot nest); add manual git worktrees if edits collide |
 | Gemini CLI | subagents-as-tools; `@agent-name` | Yes BUT strictly hub-and-spoke (no nested calls) | None → restrict parallel workers to read-only roles unless given external worktrees |
 | Cursor | Subagents w/ `is_background` frontmatter; `/multitask` | Yes | Opt-in per-subagent worktree or cloud VM |
 | Antigravity | `invoke_subagent` (async by design); `/fork` | Yes | `/fork` workspace separation; per-subagent worktrees UNVERIFIED |
 
-## Headless invocation templates (fallback workers)
-
-```
-claude    claude -p "<prompt>" --output-format json --permission-mode acceptEdits
-opencode  opencode run "<prompt>" --auto --format json
-codex     codex exec --sandbox workspace-write --json -o <out-file> "<prompt>"
-gemini    gemini --output-format json "<prompt>"
-agy       agy -p --output-format json --print-timeout 15m "<prompt>"
-```
-
-Completion signal = process exit (Claude documents 0/non-zero contract).
-NEVER pass secrets as arguments. Feature-detect old binaries via `--version`.
-
 ## Unknown platform procedure
 
 1. WEB SEARCH: `<platform> official docs MCP configuration` and