archgen-skill 0.0.4 → 0.0.6

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

@@ -1,117 +0,0 @@
-# MCP installation and skill fetching
-
-## INSTALL-MCP procedure (approval-gated)
-
-1. **Identify** the platform (SKILL.md Step 0), load its row from
-   references/platforms.md section MCP: config file, top-level key, quirks.
-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>`
-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.
-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. Uncertainty
-triggers web-search of current official docs, never invention.
-
-## FETCH-SKILL procedure
-
-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",
-  "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

@@ -1,169 +0,0 @@
-# Orchestration playbook — survey, verify, dispatch
-
-Sub-agent briefs and the wave-execution mechanics. The orchestrator (SKILL.md)
-calls into these sections; workers never read this file.
-
-## §survey — brownfield codebase analysis brief
-
-Dispatch 1–2 sub-agents with this prompt shape:
-
-```
-TASK: Survey this repository to prepare a feature plan for: <feature request>
-DELIVERABLE: write .archgen/<slug>/codebase-map.md containing EXACTLY these
-sections:
-  ## Structure      — top-2-levels folder tree w/ one-line purpose each
-  ## Modules        — table: module | responsibility | key entry points
-  ## Conventions    — naming, error-handling, test layout actually observed
-  ## Affected       — files/modules the feature will touch, with evidence paths
-SCOPE: read-only. Use codegraph MCP tools when available
-(codegraph_explore / codegraph_files); otherwise Glob+Grep systematically.
-VERIFY: every claim cites a real path; no guessed APIs.
-```
-
-Accept the map only if every section is present and non-empty.
-
-## §verifier — plan review brief
-
-Dispatch AFTER artifacts exist and validate.mjs passes. The verifier:
-
-1. Runs `node <skill>/scripts/verify-plan.mjs .archgen/<slug>/tasks.yaml --plan .archgen/<slug>/plans`
-   — deterministic floor: cycles, dangling refs, same-wave ownership overlap,
-   missing acceptance criteria, plan↔task coverage.
-2. Reads plans + tasks.yaml and judges what scripts cannot:
-   - Are wave boundaries sensible (no artificial serialization)?
-   - Do acceptance criteria objectively verify (command or observable)?
-   - Edge cases covered per SKILL.md right-sizing class?
-   - Code-standards compliance plausible for the planned structure?
-3. Returns EXACTLY one line verdict: `APPROVE` or `ISSUES:` + numbered list.
-
-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
-
-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.
-- Cursor: background subagents; request isolation when >2 parallel workers.
-- Antigravity: invoke_subagent async.
-- Codex: spawn_agent works but children can't nest — flatten the plan instead.
-- 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.
-
-### When sub-agents are unavailable or fail
-
-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:
-
-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"
-# point the sub-agent's cwd at .worktrees/$id, then merge task-$id on success
-```
-
-### 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.
-
-Workers do NOT talk to each other; coordination happens only through
-tasks.yaml state.
-
-## Failure policy
-
-- 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
-  failed task's globs.

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

@@ -1,83 +0,0 @@
-# Platform capability matrix (August 2026)
-
-Facts verified against official vendor docs; cells marked UNVERIFIED could not be
-confirmed. The orchestrator loads ONLY the row matching Step-0 detection.
-
-## Skill install paths
-
-| Platform | Project path | Global path | Notes |
-|---|---|---|---|
-| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` | Plugin marketplace: `/plugin install x@mkt`; skills hot-reload |
-| OpenCode | `.opencode/skills/` (+ reads `.claude/`, `.agents/`) | `~/.config/opencode/skills/` (+ `~/.claude/`, `~/.agents/`) | Walks up to git root |
-| Cursor | `.agents/skills/`, `.cursor/skills/` | `~/.agents/skills/`, `~/.cursor/skills/` | ≥2.4 native; also scans `.claude/`, `.codex/`; nesting OK |
-| Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | Enterprise system paths also read |
-| VS Code + Copilot | `.github/skills/` (+ `.claude/`, `.agents/`) | `~/.copilot/skills/` (+ `~/.claude/`, `~/.agents/`) | Extra dirs via chat.agentSkillsLocations |
-| Codex CLI | `.agents/skills/` (crawls up to repo root) | `~/.agents/skills/` (legacy `~/.codex/skills/`) | `$skill-installer` built in |
-| Gemini CLI | `.gemini/skills/` or `.agents/skills/` | `~/.gemini/skills/` or `~/.agents/skills/` | `gemini skills install <git-url> --consent` |
-| Antigravity | `<ws>/.agents/skills/` | `~/.gemini/config/skills/` | Backward-supports `.agent/skills`; name frontmatter OPTIONAL here |
-| Zed | `<project>/.agents/skills/` ONLY | `~/.agents/skills/` ONLY | FLAT layout — no nesting; worktree-trust gate on project skills |
-| Kiro | `.kiro/skills/` | `~/.kiro/skills/` | Custom agents need explicit `resources: ["skill://.kiro/skills/**/SKILL.md"]` |
-| Trae | `.trae/skills/` (opt-in `.agents/`) | `~/.trae/skills/` | `.trae` wins collisions; CN variant separate |
-| Claude Desktop | — (account-scoped) | GUI ZIP upload only | Scripts run sandboxed, NOT local shell |
-
-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`:
-
-| Platform | File(s) | Key | stdio fields | Remote URL field | CLI add? |
-|---|---|---|---|---|---|
-| Claude Code | `.mcp.json` (project) / `~/.claude.json` (local/user) | `mcpServers` | command,args[,env] type:"stdio" | `url`+headers type:"http"/"sse" | `claude mcp add --scope project\|local\|user --transport stdio\|http\|sse` |
-| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\` (Win) / `~/.config/Claude/` (Linux) | `mcpServers` | command,args,env | UI Connectors preferred; file `url` UNVERIFIED | none |
-| OpenCode | `opencode.json(c)` / `~/.config/opencode/opencode.json(c)` | **`mcp`** | type:"local", **command:[array]**, environment{} | type:"remote", `url`, headers | `opencode mcp add` (interactive only) |
-| Cursor | `.cursor/mcp.json` / `~/.cursor/mcp.json` | `mcpServers` | command,args,env,cwd | `url`+headers (`${env:VAR}` interp.) | none (deep-links UNVERIFIED) |
-| VS Code Copilot | `.vscode/mcp.json` / profile mcp.json / portable `.mcp.json` | **`servers`** (+inputs[]) | type:"stdio",command,args,env | type:"http"/"sse", url, headers | `copilot mcp add`; palette "MCP: Add Server" |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` (global only) | `mcpServers` | command,args,env | **`serverUrl`** OR `url` + headers | none (Marketplace UI/deeplink) |
-| Codex CLI | `~/.codex/config.toml` / project `.codex/config.toml` (trust-gated) | `[mcp_servers.<id>]` TOML | command,args,env,cwd | `url`, bearer_token_env_var, http_headers | `codex mcp add <n> --url \| -- cmd args` |
-| Gemini CLI | `~/.gemini/settings.json` / `.gemini/settings.json` | `mcpServers` | command,args,env,cwd,trust | `httpUrl`(HTTP)/`url`(SSE)+headers | `gemini mcp add -s user\|project -t stdio\|sse\|http` |
-| Antigravity | `~/.gemini/config/mcp_config.json` / `.agents/mcp_config.json` | `mcpServers` | command,args,env,cwd | **`serverUrl` MANDATORY — `url` rejected** + headers/oauth | none (`/mcp` overlay manager) |
-| Zed | `~/.config/zed/settings.json` / `.zed/settings.json` | **`context_servers`** | command,args,env | `url`+headers (OAuth auto-prompt) | none (Settings UI writes file) |
-| Kiro | `.kiro/settings/mcp.json` / `~/.kiro/settings/mcp.json` | `mcpServers` | command,args,env,disabled,autoApprove | `url`+headers+oauth | `/mcp add` (CLI session) |
-| Trae IDE | `.trae/mcp.json` | `mcpServers` | command,args,env | url + type:"sse"/"http" | none (UI manual add) |
-
-Restart semantics: full restart needed = Claude Desktop, Windsurf, Zed.
-Hot-reload = Kiro, Gemini, Codex. Approval prompt on first detection =
-Claude Code project-scope servers.
-
-## Sub-agent dispatch capability
-
-| Harness | Native mechanism | Parallel background | Isolation for parallel edits |
-|---|---|---|---|
-| 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 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 |
-
-## Unknown platform procedure
-
-1. WEB SEARCH: `<platform> official docs MCP configuration` and
-   `<platform> agent skills install path`.
-2. Prefer official vendor domains over blog posts; note the date of sources.
-3. Present findings + proposed config diff to the user. [approval gate]
-4. Apply, verify, and offer to append findings to this table upstream.