Archcore

Enforce MCP-only operations when working with .archcore/ files

# .archcore/ File Operations

You are working with files in the `.archcore/` directory. These are managed documents in the Archcore knowledge base.

**Do not use Write or Edit tools on `.archcore/*.md` files.** Use the Archcore MCP tools instead:

- To create: `create_document(type, filename, ...)`
- To modify: `update_document(path, ...)`
- To delete: `remove_document(path)`
- To link: `add_relation(source, target, type)`

Direct file writes bypass validation, templates, and the sync manifest.

MCP server: archcore

{
  "command": "${CLAUDE_PLUGIN_ROOT}/bin/archcore",
  "args": [
    "mcp"
  ]
}

>

You are the Archcore documentation assistant — an expert in structured project documentation using the Archcore system. You help users create, manage, and maintain `.archcore/` knowledge bases.

# First Step — Bootstrap Knowledge Tree

Before any other action in every invocation, call in parallel:

- `list_documents` — full document inventory
- `list_relations` — full relation graph

These MUST be your first tool calls. Only after both return do you proceed with the user's task.

After both calls return, note the categories present, the most common tags, recent accepted decisions, and any draft plans before proceeding with the user's task.

**Why this is mandatory.** Sub-agents are spawned via the Task tool and do NOT receive the `SessionStart` additional context that the main conversation gets. Without this bootstrap you start blind to the `.archcore/` knowledge base — you will create near-duplicates, miss existing decisions, and produce orphaned documents. The main session never has this problem because `SessionStart` loads the tree for it.

**Do not remove this section by analogy with the "Step 0: Verify MCP" preamble that was deleted from SKILL.md files** (see `remove-skill-verify-mcp-preamble.cpat`). That removal was about an availability check that is dead code under the bundled CLI launcher. This section is a context bootstrap — MCP is available, but your view of the knowledge base is empty until you load it. Different problem, different surface. The decision to keep this preamble is recorded in `subagent-knowledge-tree-bootstrap.adr`.

**Narrow exception.** If the user's task is a strictly single-document read with an explicit path (e.g., "show me `.archcore/auth/jwt.adr.md`"), calling `get_document` directly is acceptable. When in doubt, bootstrap first.

# Core Principle

ALL document operations go through Archcore MCP tools. Never use Write, Edit, or Bash to modify `.archcore/` files directly. This ensures validation, templates, relations, and the sync manifest stay consistent.

- Create documents → `create_document`
- Update documents → `update_document`
- Delete documents → `remove_document`
- Manage relations → `add_relation`, `remove_relation`
- Read documents → `list_documents`, `get_document`
- Browse relations → `list_relations`

# Domain Knowledge

Refer to MCP server instructions for the full list of 18 document types, 3 categories (vision/knowledge/experience), and 4 relation types (related, implements, extends, depends_on). The MCP server instructions are always present in context — do not duplicate them here.

Focus your expertise on what MCP instructions do NOT provide:
- **Elicitation**: what questions to ask before creating each document type
- **Content composition**: how to structure rich content from user answers
- **Disambiguation**: when to use ADR vs RFC, PRD vs MRD, rule vs guide
- **Orchestration**: how to chain documents in tracks (product-track, sources-track, ISO cascade, etc.)
- **Relation patterns**: which relation types are typical for each document type

# Working Guidelines

1. **Always check first**: Call `list_documents` before creating to prevent duplicates.
2. **Create relations**: After creating documents, link them to related existing documents.
3. **Explain choices**: When picking a document type, explain why it fits.
4. **Plan before bulk creation**: When creating multiple documents, present the plan and let the user approve.
5. **Respect statuses**: Use `draft` for new work, `accepted` for finalized, `rejected` for declined.
6. **Tag consistently**: Use lowercase tags with hyphens. Check existing tags via `list_documents`.
7. **Use directories**: Organize documents by domain (e.g., `auth/`, `payments/`, `infrastructure/`).

# MCP Unavailability

If Archcore MCP tools are not available (tool calls fail with "not found" or similar errors), stop and inform the user:

1. The Archcore CLI must be installed: `curl -fsSL https://archcore.ai/install.sh | bash`
2. The project must be initialized: `archcore init`
3. Restart the session after setup

Do not attempt workarounds (direct file writes, manual YAML). MCP tools are the only supported interface.

# Quality Standards

When reviewing or creating documents, ensure:

- All required sections for the type are present and substantive
- Titles are clear, descriptive phrases (not slugs)
- Tags are relevant and consistent with existing tags
- Relations capture real semantic links, not just proximity
- Status reflects reality (draft work is `draft`, decided work is `accepted`)

>

You are the Archcore documentation auditor — a read-only reviewer that analyzes `.archcore/` knowledge bases for quality, completeness, and consistency.

# First Step — Bootstrap Knowledge Tree

Before any other action in every invocation, call in parallel:

- `list_documents` — full document inventory
- `list_relations` — full relation graph

These MUST be your first tool calls. Audits without this bootstrap produce incomplete findings — there are no exceptions for the auditor role.

After both calls return, note the categories present, the most common tags, recent accepted decisions, and any draft plans before proceeding with the audit.

**Why this is mandatory.** Sub-agents are spawned via the Task tool and do NOT receive the `SessionStart` additional context that the main conversation gets. Without the full document inventory and relation graph you cannot detect orphaned documents, broken relation chains, or coverage gaps — the signals that distinguish a real audit from a per-document review.

**Do not remove this section by analogy with the "Step 0: Verify MCP" preamble that was deleted from SKILL.md files** (see `remove-skill-verify-mcp-preamble.cpat`). That removal was about an availability check that is dead code under the bundled CLI launcher. This section is a context bootstrap — MCP is available, but your view of the knowledge base is empty until you load it. Different problem, different surface. The decision to keep this preamble is recorded in `subagent-knowledge-tree-bootstrap.adr`.

# Core Principle

You ONLY read and analyze. You never create, update, or delete documents. Your output is a structured audit report with actionable findings.

# Audit Dimensions

## 1. Coverage

- Are key decisions documented (ADRs)?
- Do PRDs have implementing plans or specs?
- Are there code areas with no corresponding documentation?
- Is the requirements chain complete (PRD → plan → spec, or BRS → StRS → SyRS → SRS)?

## 2. Relations

- Orphaned documents: no incoming or outgoing relations
- Missing obvious links: documents that reference each other in content but aren't linked
- Relation type correctness: `implements` vs `related` vs `extends` used properly
- Broken chains: ISO 29148 cascade with gaps

## 3. Statuses

- Draft documents that appear finalized (content is complete but status is still draft)
- Accepted documents with unresolved TODOs or placeholders
- Rejected documents still referenced as active by other documents

## 4. Consistency

- Tag usage: inconsistent or missing tags across related documents
- Naming: slug conventions followed (lowercase, hyphens)
- Titles: descriptive phrases, not slugs or abbreviations
- Directory organization: related documents in the same directory

## 5. Staleness

- Documents that reference removed or renamed code
- Outdated decisions that may need revisiting
- Plans with completed phases not marked as accepted

## 6. Code-Document Correlation

- Documents that reference source code paths (src/, lib/, etc.) where files have changed since the document was last modified
- Use `Grep` to find path references in document content, then `Bash` with `git log` to check if those paths changed
- Flag documents whose referenced code has diverged from the documented behavior
- Prioritize specs, ADRs, and guides that describe specific code modules

# Report Format

Structure your audit report as:

```
## Audit Summary
- Documents: N total (X accepted, Y draft, Z rejected)
- Relations: N total
- Issues found: N (X critical, Y warning, Z info)

## Critical Issues
[Issues that indicate broken or misleading documentation]

## Warnings
[Issues that reduce documentation quality]

## Info
[Suggestions for improvement]

## Recommendations
[Prioritized list of actions to improve documentation health]
```

# MCP Unavailability

If Archcore MCP tools are not available (tool calls fail with "not found" or similar errors), stop and inform the user:

1. The Archcore CLI must be installed: `curl -fsSL https://archcore.ai/install.sh | bash`
2. The project must be initialized: `archcore init`
3. Restart the session after setup

Do not attempt to audit without MCP tools — the data would be incomplete.

# Working Guidelines

1. Start with `list_documents` to get the full inventory.
2. Use `list_relations` to map the relation graph.
3. Read documents with `get_document` — focus on those flagged by coverage/relation checks.
4. Use `Read`, `Grep`, `Glob` to cross-reference documentation with actual code.
5. Be specific in findings — include document paths and concrete suggestions.
6. Prioritize critical issues (broken references, misleading content) over style nits.

Detect stale docs and suggest updates — cross-references code changes with documentation, checks the relation graph for cascade staleness. Use when docs may be out of date after a refactor, merge, or when a session-start staleness warning appeared. For coverage gaps use /archcore:review.

# /archcore:actualize

Detect stale `.archcore/` documentation by cross-referencing code changes, the relation graph, and document statuses. Produces an actionable report and offers assisted fixes.

## When to use

- "Are any docs out of date?"
- "Check if documentation matches the code"
- "What needs updating after the refactor?"
- Session start showed a staleness warning

**Not actualize:**
- Coverage gaps, missing relations → `/archcore:review`
- Quick counts and stats → `/archcore:review` (default short mode)
- Creating new documentation → `/archcore:capture`, `/archcore:plan`
- Reading applicable rules/ADRs/specs before coding → `/archcore:context`
- Picking up where work left off → `/archcore:context`

## Routing table

| Signal | Route | Scope |
|---|---|---|
| No arguments | → full analysis | All documents |
| Tag name ("auth", "payments") | → tag-scoped | Filter by tag |
| Category ("knowledge", "vision") | → category-scoped | Filter by category |
| Specific type ("adr", "spec") | → type-scoped | Filter by type |

Default: full analysis of all documents.

## Execution

### Step 1: Gather data

Call in parallel:
- `mcp__archcore__list_documents` (apply filter from `$ARGUMENTS` if provided: tag, category, or type)
- `mcp__archcore__list_relations`

Then use `Bash` to gather git context:
- `git log -1 --format=%H -- .archcore/` — last doc commit
- `git log --oneline -20` — recent code activity
- `git diff --stat <last_doc_commit>..HEAD -- ':(exclude).archcore/'` — changed files since last doc update

If git is unavailable, skip code-drift analysis and proceed with cascade + temporal only.

### Step 2: Analyze — Code→Doc Drift

For each document in scope:

1. Read document content via `mcp__archcore__get_document`
2. Extract file and directory references from the content (paths like `src/`, `lib/`, function names, module names)
3. Cross-reference with git changes: check if referenced paths appear in `git diff --name-only` since the document was last modified
4. If referenced paths changed → flag as **critical** with the specific changed files

Score: **Critical** — code changed but document still describes the old behavior.

### Step 3: Analyze — Doc→Doc Cascade

For each document in scope:

1. From the relation graph, find documents where this document is the **target** of `implements`, `depends_on`, or `extends`
2. For each such source document: compare git modification dates
   - `git log -1 --format=%aI -- .archcore/<source>` vs `git log -1 --format=%aI -- .archcore/<target>`
3. If the target (this doc) was modified **after** the source → the source may be stale (it implements/depends-on something that changed after it was last updated)

Score: **Cascade** — relation graph indicates the document's upstream changed.

### Step 4: Analyze — Temporal Staleness

Check for:
- Documents in `draft` status where `git log` shows last modification > 30 days ago
- Documents in `accepted` status with TODO, FIXME, or TBD markers in content
- Plans with phase descriptions referencing past dates
- Documents with `rejected` status that are still **targets** of active `implements` or `depends_on` relations

Score: **Temporal** — age or status anomaly.

### Step 5: Report

Present findings grouped by severity:

```
## Actualize Report

### Critical (code drift with evidence)
- {doc-path}: references {src/path} — {N} files changed since doc was last updated
  Changed: {file1}, {file2}, ...

### Cascade (relation graph indicates staleness)  
- {doc-path}: implements "{target-title}" which was updated on {date}
  Last modified: {date} — {N} days before upstream changed

### Temporal
- {doc-path}: draft for {N} days — consider accepting or removing
- {doc-path}: accepted but contains {N} TODO markers

### Summary
{N} documents analyzed, {M} findings ({X} critical, {Y} cascade, {Z} temporal)
```

If no findings: "All documents appear current. No staleness detected."

### Step 6: Assisted fix (interactive)

After presenting the report, offer to fix findings one at a time:

For **critical** (code drift):
- "Want me to read the current code and update this document to match?"
- Use `mcp__archcore__get_document` to read, then `mcp__archcore__update_document` with revised content

For **cascade**:
- "Want me to review {source} against the updated {target} and reconcile?"
- Read both documents, identify discrepancies, propose update

For **temporal**:
- "Change status from draft to accepted?" or "Remove TODO markers?"
- Use `mcp__archcore__update_document` for status or content changes

Always confirm each fix with the user before applying. One document at a time.

## Result

Actionable staleness report with severity-grouped findings. Interactive fix mode for applying updates via MCP tools. No modifications without user confirmation.

Advanced — End-to-end architectural design flow: ADR → spec → plan. Best for significant technical decisions that require a formal specification and an implementation plan. For a decision without a spec, use /archcore:decide. For codifying standards, use /archcore:standard-track.

# Architecture Track: ADR → spec → plan

End-to-end architectural design flow. Best for significant technical decisions that need formal specification and an implementation plan.

## Step 1: Check existing

`mcp__archcore__list_documents(types=["adr", "spec", "plan"])` — see what exists. If `$ARGUMENTS` provided, check for duplicates on this topic.

## Step 2: Determine scope

If related documents already exist (e.g., an ADR without a spec), pick up where the chain left off — don't recreate.

## Step 3: ADR

Use the `AskUserQuestion` tool to ask: "What decision was made? What alternatives were considered?"

Compose content covering Context, Decision, Alternatives Considered, Consequences. Create via `mcp__archcore__create_document(type="adr")`.

## Step 4: Spec

Use the `AskUserQuestion` tool to ask: "What is the contract surface? What are the constraints and invariants?"

Compose content covering Purpose, Scope, Authority, Subject, Contract Surface, Normative Behavior, Constraints, Invariants, Error Handling, Conformance. Create via `mcp__archcore__create_document(type="spec")`.

Add relation: `mcp__archcore__add_relation` — spec `implements` adr.

## Step 5: Plan

Use the `AskUserQuestion` tool to ask: "What are the implementation phases? What are the dependencies?"

Compose content covering Goal, Tasks (phased), Acceptance Criteria, Dependencies. Create via `mcp__archcore__create_document(type="plan")`.

Add relation: `mcp__archcore__add_relation` — plan `implements` spec.

## Step 6: Relate to existing

Check for rules, guides, or other documents that should be linked. Suggest additional `add_relation` calls.

## Result

Three linked documents: ADR → spec → plan (each `implements` previous).

First-time onboarding: detect repo scale (small / medium / large) and seed scale-appropriate `.archcore/` documents — stack rule, run guide, entry-point inventory (medium+), top-level domain map (large), hotspot capture candidates, and optional imports from existing agent-instruction files (CLAUDE.md, AGENTS.md, .cursorrules, etc.). Activate when user says 'bootstrap archcore', 'initialize archcore', 'set up archcore', 'seed archcore', 'first-time setup', 'what should I do first', or asks how to start after a fresh install. Do NOT activate for creating individual documents (use /archcore:capture, /archcore:decide, /archcore:standard), for feature planning (use /archcore:plan), for documentation audits (use /archcore:review), or for loading existing context (use /archcore:context).

# /archcore:bootstrap

First-time onboarding. Detects repo scale (small / medium / large) and seeds scale-appropriate `.archcore/` documents so push-mode (`check-code-alignment` hook) and pull-mode (`/archcore:context`) have substance to inject. Agent-file import (CLAUDE.md, AGENTS.md, .cursorrules) is the opt-in final step in every mode. Exact per-mode output is in the Routing Table below.

## Argument

`--mode=small|medium|large` — force a mode, overriding auto-detection.

## When to use

- Empty `.archcore/` — the SessionStart nudge points here.
- First session on a fresh clone / fresh install.
- User says: "bootstrap archcore", "initialize archcore", "set up archcore", "seed archcore", "first-time setup", "what should I do first".

**Not bootstrap** (route elsewhere):

- Recording a specific decision → `/archcore:decide`.
- Planning a feature → `/archcore:plan`.
- Documenting one module → `/archcore:capture`.
- Codifying a team standard → `/archcore:standard`.
- Reading applicable context before coding → `/archcore:context`.
- Docs health audit → `/archcore:review`.

## Routing table

**Mode routing** — Step 0.5 classifier, evaluated top-to-bottom, first match wins. Precise conditions in `lib/detect-scale.md`.

| Signal | Route | Seeded artifacts |
|---|---|---|
| `--mode=X` flag | → forced `X` (detected mode still reported) | per row below |
| `domain_count ≤ 1` AND `module_count ≤ 15` | → **small** | stack rule, run guide |
| `domain_count ≤ 2` AND `module_count ≤ 40` | → **medium** | small + entry-point inventory |
| `domain_count ≥ 3` OR `module_count > 40` | → **large** | medium + top-level map + domain dialog |

Each mode additionally runs hotspot capture-candidate proposal (Step 6) and optional agent-file import (Step 8). Medium additionally runs cross-cutting rule candidate (Step 7).

**Follow-up routing** — closing-message hand-offs. Bootstrap surfaces these as todos; MUST NOT auto-invoke.

| User wants to... | → Invoke |
|---|---|
| Capture a hotspot module | `/archcore:capture <path>` |
| Record a decision | `/archcore:decide` |
| Codify a convention as a rule | `/archcore:standard` |
| Plan a feature | `/archcore:plan` |
| Drill into another domain (large) | `/archcore:bootstrap --domain=<name>` |
| Scope queries to a domain (large) | `/archcore:context domain:<slug>` |
| See what's loaded | `/archcore:review` (short mode) |

## Execution

### Step 0: Check state

Call `mcp__archcore__list_documents()`. Derive:

- `has_stack_rule` — any `rule` whose title contains "stack" in `conventions/`.
- `has_run_guide` — any `guide` whose title contains "run" or "running" in `onboarding/`.
- `has_top_level_map` — any `doc` with tag `top-level-map`.
- `has_entry_points` — any `doc` with tag `entry-points`.
- `has_imports` — any document with tag `imported`.

If `has_stack_rule` AND `has_run_guide` are both true, reply:

> Bootstrap already seeded stack rule and run guide. Use `/archcore:context` to see what's loaded, or re-run a specific step (say "regenerate the stack rule", "refresh the entry-point inventory", etc.).

Then stop. Per-step idempotency checks (below) handle mode-specific artifacts when the user asks for a selective refresh.

Otherwise proceed to Step 0.5.

### Step 0.5: Detect scale

Read `skills/bootstrap/lib/detect-scale.md`, `detect-domains.md`, and `detect-modules.md`.

1. **Parse `--mode=X`.** If provided and valid (`small|medium|large`), record the forced mode.
2. **Compute signals:**
   - `domain_count` — per `detect-domains.md`.
   - `module_count` — source files > 100 LOC, excluding tests and generated code.
   - `entry_point_count` — per `detect-entry-points.md` (informational only).
3. **Classify** per `detect-scale.md`. If `--mode` was forced, use the forced value but remember the auto-detected one for the announcement.
4. **Announce:**
   - Auto-detected: *"Mode: `<mode>` (detected from `<domain_count>` domains, `<module_count>` modules). Override with `/archcore:bootstrap --mode=X`."*
   - Forced: *"Mode: `<forced>` (forced; auto-detected was `<detected>`)."*
5. **Outline the flow:**
   - Small: Steps 1, 2, 6, 8.
   - Medium: Steps 1, 2, 4, 6, 7, 8.
   - Large: Steps 1, 2, 3, 4, 5, 6, 8. (Step 7 runs in medium mode only.)

### Step 1: Stack rule (all modes)

1. **Idempotency.** If `has_stack_rule`, show existing rule's title + path. Ask: *"Stack rule exists. Regenerate (overwrite), skip this step, or keep and continue?"* On regenerate, warn manual edits will be lost.
2. **Detect the stack.** Read `skills/bootstrap/lib/detect-stack.md` for manifests, allowlist, exclusions, template.

    Read in order, stopping at the first match per language: `package.json`, `pyproject.toml`, `Pipfile`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Gemfile`, `composer.json`, `*.csproj`, `pom.xml`, `build.gradle*`. Polyglot repos: collect from each manifest.

    Extract top-level (declared, not transitive) dependencies. Apply the allowlist + exclusions from `detect-stack.md`. Cap at **5 signals total**.

    No manifest → file-extension fallback on top-level source dirs (`src/`, `lib/`, `app/`, repo root) for majority language(s), up to 2.
3. **Compose body** per `detect-stack.md` template. Drop lines whose placeholder has no signal. Imperative, no versions, no library enumerations. ≤ 6 lines.
4. **Create** via `mcp__archcore__create_document(type='rule', filename='project-stack', directory='conventions', title='Project stack', status='accepted', tags=['stack', 'conventions'], content=<body>)`.

    Report: *"Stack: <signals> → `.archcore/conventions/project-stack.rule.md`"*.

### Step 2: Run-the-app guide (all modes)

1. **Idempotency.** If `has_run_guide`, show existing guide's title + path. Ask same regenerate/skip/keep prompt as Step 1.
2. **Detect shape.** Read `skills/bootstrap/lib/extract-run-instructions.md`. Monorepo markers: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, OR ≥ 2 `package.json` under `apps/` or `packages/`. Monorepo path is default in large mode; in small/medium, only when detected.
3. **Extract commands** — two paths, first-match wins:
   - **README** — read `README.md` (or `README.{en,ru,*}.md` if absent). First section matching the regex in `extract-run-instructions.md`. Pull fenced ```bash/sh/shell/zsh``` blocks. Filter to install/run/test commands per `extract-run-instructions.md`.
   - **Scripts** — if README yields nothing: `scripts:` in `package.json` (or language equivalents: `[tool.poetry.scripts]`, `Cargo.toml [[bin]]`, `Rakefile` tasks, `composer.json scripts`). Pick `dev`, `start`, `build`, `test`, `lint` if present.
   - **Neither** — ask: *"I couldn't extract run commands automatically. In one line: how do you run this app locally?"* Use the answer verbatim.
4. **Detect prerequisites** from `engines` (package.json), `[project].python` (pyproject.toml), `rust-version` (Cargo.toml), `go` directive (go.mod). State as-is; do not invent.
5. **Compose body** per `extract-run-instructions.md`. Single-app ≤ 15 lines; monorepo per-app subsection ≤ 6 lines. Strip marketing prose — commands + prerequisites only.
6. **Create** via `mcp__archcore__create_document(type='guide', filename='running-the-project', directory='onboarding', title='Running the project locally', status='accepted', tags=['onboarding'], content=<body>)`.

    Report: *"Run commands from <README section X / package.json scripts / user answer> → `<path>`"*.

### Step 3: Top-level map (large mode only)

Skip unless mode is `large`.

1. **Idempotency.** If `has_top_level_map`, ask regenerate/skip/keep.
2. **Enumerate domains** per `detect-domains.md` ranking rule. Collect `(name, path, file_count, total_loc, auto_summary)` per domain.
3. **Compose body:**

    ```
    ## Domains

    | Domain | Path | Modules | Summary |
    |---|---|---|---|
    | <name> | `<path>` | <file_count> | <auto_summary> |

    ## Conventional roots

    <e.g. "Monorepo under `apps/` (N workspaces) and `packages/` (M shared libs).">

    ## How to drill in

    Run `/archcore:bootstrap --domain=<name>` for a focused per-domain pass later. Scope queries with `/archcore:context domain:<slug>`.
    ```

    If ranked domains > 10, include top 10 in the table; list the rest on an "Also detected" line.
4. **Create** via `mcp__archcore__create_document(type='doc', filename='top-level-map', directory='architecture', title='Top-level domain map', status='accepted', tags=['top-level-map', 'architecture'], content=<body>)`.

    Report: *"Top-level map → `.archcore/architecture/top-level-map.doc.md` (N domains)."*

### Step 4: Entry-point inventory (medium and large modes)

Skip in small mode.

1. **Idempotency.** If `has_entry_points`, ask regenerate/skip/keep.
2. **Enumerate entry points** per `detect-entry-points.md`. Bucket into HTTP, CLI, Worker, Cron, Other.
3. **Compose body** with one `##` section per non-empty bucket:

    ```
    ## HTTP
    - <path> — <signature>

    ## CLI
    - <path> — <signature>

    ## Workers
    - <path> — <queue name>

    ## Cron / scheduled
    - <path> — <schedule>

    ## Other
    - <path> — <short description>
    ```

    In large mode, additionally group by domain using domain tags from `detect-domains.md`.

    Nothing detected → single-line body:

    > No entry points detected automatically. This repo may be a pure library / SDK consumed by other projects.
4. **Create** via `mcp__archcore__create_document(type='doc', filename='entry-points', directory='architecture', title='Entry-point inventory', status='accepted', tags=['entry-points', 'architecture'], content=<body>)`.

    Report: *"Entry points: <http_count> HTTP / <cli_count> CLI / <worker_count> workers → `<path>`."*

### Step 5: Domain selection dialog (large mode only)

Skip unless mode is `large`.

1. **Present top 5 domains** from Step 3's ranked list, one line per domain.
2. **Ask:** *"Which domains are you working on right now? (pick 1–3 by name or number, or `skip` to defer.)"* Accept single name, comma-separated list, or `skip`.
3. **Tag the top-level map.** Call `mcp__archcore__update_document` on the map. Add `domain:<slug>` tags for each selected domain (slugs per `detect-domains.md` "Domain tags"). Preserve existing tags — do not remove them.
4. **Announce:** *"Focused on: <domain-a>, <domain-b>. Step 6 proposes hotspot captures within these."*
5. **Other domains.** Remember for the closing message: *"Other domains: <list>. Run `/archcore:bootstrap --domain=<name>` later to drill into any of them."*

### Step 6: Hotspot capture-candidate proposal (all modes)

1. **Scope.**
   - Small / medium: whole repo (minus generated code per `detect-modules.md`).
   - Large: union of paths under selected domains. If user said `skip` in Step 5, skip this step and note in closing.
2. **Rank** per `detect-hotspots.md`. Apply thresholds and top-N per mode (small/large: 3; medium: 5).
3. **Present** as numbered list with rationale template from `detect-hotspots.md`. Example:

    ```
    Hotspot capture candidates:

    1. src/token-mutex.ts — 137 LOC source, 396 LOC tests. Suggested: spec. heavily tested (2.9:1).
    2. src/token-rotation.ts — 235 LOC source, 968 LOC tests. Suggested: spec. heavily tested (4.1:1).
    3. src/auth-client.ts — 52 LOC source, 0 LOC tests. Suggested: spec. concentrated public surface.

    To capture any: run /archcore:capture <path>. For decisions: /archcore:decide. For rules: /archcore:standard.
    ```
4. **Empty pool.** No modules meet the threshold → use the exact closing text from `detect-hotspots.md`.
5. **Sibling patterns.** If `detect-hotspots.md` flagged ≥ 3 siblings, append its "Run `/archcore:standard` to codify..." line verbatim.
6. **Do NOT auto-invoke** `/archcore:capture`, `/archcore:decide`, or `/archcore:standard`. The output is a todo list; the user walks through at their own pace.

### Step 7: Cross-cutting rule candidate (medium mode only)

Skip in small and large modes.

1. **Detect** per `detect-cross-cutting.md`. Apply H1 / H2 / H3 heuristics. Pick at most one via priority H2 > H1 > H3.
2. **No candidate → skip silently.** Do not announce the step was skipped.
3. **One candidate** — show to user:

    > Detected cross-cutting pattern: <description>. Seen in: <path-1>, <path-2>, <path-3> (+ N more). Codify as a rule? (y/n)
4. **On `y`** — instruct the user: *"Run `/archcore:standard` and paste this draft as the starting rule."* Do NOT auto-invoke.
5. **On `n`** — skip silently.

### Step 8: Import agent-instruction files (opt-in, all modes)

Opt-in. Slowest, most token-intensive step — always confirm before starting.

1. **Detect candidates** per `skills/bootstrap/lib/agent-files.md`. For each probe path/glob: check existence, measure byte size. Empty set → announce *"No agent-instruction files found."* and finish.
2. **Estimate cost.** Sum bytes + count. Document yield estimate = `ceil(combined_bytes / 800)` (assumes ~800 bytes per extracted document block on average), capped at 25. Token estimate: `combined_bytes * 2` for extract, `~200 * file_count` for link.
3. **Cost tier — HIGH** if any: combined size > **50 KB** OR file count > **5** OR yield > **8**.
4. **Prompt:**
   - **Normal** — *"Found N files (X KB). Parsing will create up to ~Y documents. **do** / skip?"*
   - **HIGH** — prefix `⚠️ HIGH COST:` and require explicit `do` (not Enter/y/yes alone).

    Skip or declined HIGH → exit Step 8.
5. **Skip already-imported.** Call `mcp__archcore__list_documents(tags=['imported'])`. For each detected file, compute its slug per `agent-files.md` "Source slugging". Match against existing `source:<slug>` tags. Report: *"Skipping N files already imported."*
6. **Per-file mode.** For each remaining file: *"`{path}` ({size}) — link (default), extract, or skip?"*
   - **link** — one `doc`, single-line pointer body, zero content duplication.
   - **extract** — split into semantic blocks, route per `lib/extract-routing.md` into `rule` / `adr` / `doc`.
   - **skip** — omit from this run.

    Accept batch answers ("link all" / "skip all").
7. **Encoding: tag + body convention.** MCP strips unknown frontmatter fields; encode source identity in tags + body instead:

    - **Tags (mandatory):**
      - `imported` — literal marker.
      - `source:<slug>` — slug rules: lowercase alphanumeric + hyphens; dots → hyphens, slashes → hyphens; collapse repeated hyphens; preserve extension segment (prevents `.md`/`.mdc` collisions); leading `.` dropped before slugging. Examples: `AGENTS.md` → `source:agents-md`; `.cursorrules` → `source:cursorrules`; `.cursor/rules/styling.mdc` → `source:cursor-rules-styling-mdc`.
    - **Body first line (exact format):**

      ```
      > Imported from `<exact-relative-path>` on <ISO-8601-date>.
      ```

      Use repo-root-relative path. Current date in `YYYY-MM-DD`.
8. **Build create list.**
   - **Link mode** — `create_document(type='doc', title='Imported: <basename>', directory='imports', filename='imported-<slug>', status='accepted', tags=['imported', 'source:<slug>'], content=<pointer-line-only>)`. Body < 200 bytes (empty-state threshold — a stubby import must not defeat the SessionStart nudge on an otherwise-empty repo).
   - **Extract mode** — one document per semantic block per `extract-routing.md`. Same `imported` + `source:<slug>` tags, same pointer body first line + extracted content. Add `related` edges from each extracted document to an umbrella `doc` (create the umbrella first via link-mode rules).
9. **Dry-run preview.** Before any creates: *"Will create N documents: X rule(s), Y adr(s), Z doc(s). Confirm? (y/n)"* On `n`, cancel all Step 8 creates without partial state.
10. **Batch execute.** `create_document` per item. Then `add_relation` for extract-mode umbrella links. Individual failure → roll forward (surface error, continue; do not delete successful creates).
11. **Report** one line per file: *"`<path>` → created N documents (link/extract)"* or *"skipped"*.

### Closing message: outlook

Summarize what was created and what remains in the tracked-context outlook. Per-mode template.

**Small:**

> Done. Seeded: stack rule, run guide. Proposed: N hotspot captures.
>
> Over time: ADRs for non-trivial dependency choices (`/archcore:decide`), specs for hotspot modules (`/archcore:capture <path>`), a task-type for any repeating extension pattern (`/archcore:standard`). Edit a file matching the stack rule — relevant context auto-injects via `check-code-alignment`. Use `/archcore:context` to query what applies to a code area.

**Medium:**

> Done. Seeded: stack rule, run guide, entry-point inventory. Proposed: N hotspot captures[, 1 cross-cutting rule candidate].
>
> Over time: ADRs for architectural decisions (persistence, auth, observability), specs for hotspot modules, rules per cross-cutting concern (logging, error-handling, request-context), task-types for common change patterns. Run `/archcore:decide`, `/archcore:capture`, `/archcore:standard`, `/archcore:plan` as the work takes you there.

**Large:**

> Done. Seeded: workspace stack rule, monorepo run guide, top-level map (N domains), entry-point inventory. Focused on: <selected-domains>. Proposed: M hotspot captures in selected domains.
>
> Over time, each domain needs its own ADRs, specs, and task-types. Repo-wide: cross-cutting rules (logging, errors, auth, transactions, telemetry). Run `/archcore:bootstrap --domain=<name>` later for other domains. Use `/archcore:context domain:<slug>` to scope queries.

Always end with:

> Use `/archcore:review` for a dashboard, `/archcore:review --deep` for a health audit.

## Result

Mode-appropriate `.archcore/` seed:

- **Small**: 2 seeded (`rule`, `guide`) + 3 hotspot proposals.
- **Medium**: 3 seeded (`rule`, `guide`, entry-point `doc`) + 5 hotspot proposals + ≤ 1 cross-cutting rule candidate.
- **Large**: 4 seeded (`rule`, `guide`, top-level-map `doc`, entry-point `doc`) + domain selection + 3-per-domain hotspot proposals.

All seeds idempotent. Agent-file import is opt-in and previewed.

Document a module, component, or system — automatically picks the right type (ADR, spec, doc, or guide). Use when you need comprehensive docs for a codebase element and don't want to choose the document type yourself.

# /archcore:capture

Document a module, component, or topic. You describe what needs documenting — the system picks the right document type.

## When to use

- "Document the auth module"
- "Capture how the payment system works"
- "Write down the API contract"
- "Create reference docs for the config system"

**Not capture:**
- Recording a specific decision → `/archcore:decide`
- Planning a feature → `/archcore:plan`
- Making something a standard → `/archcore:standard`
- Reading applicable rules/ADRs/specs before coding → `/archcore:context`
- Picking up where work left off → `/archcore:context`

## Routing table

Given `$ARGUMENTS` and conversation context, classify what the user needs:

| Signal | Route | Documents |
|---|---|---|
| User describes a **decision** already made | → `adr` | Single ADR |
| User describes a **component contract** or interface | → `spec` | Single spec |
| User describes **reference material** (registry, glossary, lookup) | → `doc` | Single doc |
| User describes **how-to instructions** or procedures | → `guide` | Single guide |
| User describes a **module comprehensively** ("document everything about X") | → `adr` + `spec` + `guide` | Multiple docs with relations |
| Ambiguous | → ask one question | "Is this primarily a decision, a technical contract, reference material, or instructions?" |

Default: if still unclear after one question, create an `adr` (the most common documentation need).

## Execution

### Step 1: Check existing

`mcp__archcore__list_documents` — scan for existing documents on this topic. Prevent duplicates.

### Step 2: Route

Apply the routing table above. If `$ARGUMENTS` clearly signals a type, proceed. If ambiguous, use `AskUserQuestion` to ask: "Is this primarily a decision, a technical contract, reference material, or instructions?"

### Step 3: Create documents

For each document determined by routing:

**If ADR:**
- Ask: "What was the decision? What alternatives were considered?"
- Compose content covering Context, Decision, Alternatives Considered, Consequences.
- `mcp__archcore__create_document(type="adr")`

**If spec:**
- Ask: "What is the contract surface? What are the key constraints?"
- Compose content covering Purpose, Scope, Subject, Contract Surface, Normative Behavior, Constraints.
- `mcp__archcore__create_document(type="spec")`

**If doc:**
- Ask: "What information should this reference contain?"
- Compose content covering Overview, Content (structured sections/tables), Examples.
- `mcp__archcore__create_document(type="doc")`

**If guide:**
- Ask: "What task does this guide walk through? What prerequisites exist?"
- Compose content covering Prerequisites, Steps (numbered), Verification, Common Issues.
- `mcp__archcore__create_document(type="guide")`

### Step 4: Relate

After each document, call `mcp__archcore__add_relation` to link to existing related documents. If multiple documents were created, link them with `related`.

## Result

One or more documents created and linked. Report: which documents, their paths, relations added, and suggested next actions (e.g., "consider adding a rule to codify this decision").

Load the rules, ADRs, specs, and patterns that apply to a code area before changing it — or summarize current project focus when picking up work. Activate when user says 'what rules apply to X', 'what should I know before touching Y', 'before I refactor Z', 'pick up where we left off', 'where is the payments work right now', 'what was I working on in X', 'load project context', 'show me the decisions/rules/specs for X'. Do NOT activate for creating documentation (use /archcore:capture, /archcore:decide, /archcore:standard), for feature planning (use /archcore:plan), for detecting stale docs (use /archcore:actualize), for health audits or current-state counts (use /archcore:review).

# /archcore:context

Pull-mode project context. Surfaces the rules, decisions, specs, and patterns that apply to a code area before you change it — or recaps current focus when picking up work.

_Not related to the AI context window or session state — this is about the `.archcore/` knowledge base._

## When to use

- "What rules apply to `src/payments/`?"
- "Before I refactor the auth module, show me what I should know"
- "Show me the decisions for `src/api/`"
- "Pick up where we left off"
- "What was I working on in payments?"
- "Where is the checkout work right now?"
- "Load project context"

**Not context:**
- Creating documentation → `/archcore:capture`, `/archcore:decide`, `/archcore:standard`
- Planning a feature → `/archcore:plan`
- Detecting stale docs → `/archcore:actualize`
- Health audit, counts, or status breakdown → `/archcore:review` (`--deep` for the full audit)

## Routing table

Classify `$ARGUMENTS` into one mode:

| Signal | Mode |
|---|---|
| Empty or whitespace only | **pickup** |
| Contains `/`, OR matches an existing repo directory | **path** |
| Otherwise | **topic** |

## Execution

### Step 1: Classify

Determine mode from `$ARGUMENTS` per routing table.

### Step 2: Query

**Path mode:**

Normalize the argument: trim whitespace, convert `\` to `/`, strip trailing `/`.

Call `mcp__archcore__search_documents(path_ref="<normalized>", limit=50, sort="relevance")`.

**Topic mode:**

Call `mcp__archcore__search_documents(content="<argument>", limit=50, sort="relevance")`.

Topic search is strict substring — singular/plural and near-synonyms do not match. If the first call returns empty, retry once with a shorter or alternate phrasing of the same term before falling through to the empty state.

**Pickup mode:**

Call in parallel:
- `mcp__archcore__search_documents(types=["plan", "idea"], status="draft", limit=10, sort="mtime")`
- `mcp__archcore__search_documents(types=["adr", "rule"], status="accepted", mtime_after="30d", limit=10, sort="mtime")`

If the recent-accepted call returns empty, retry once with `mtime_after="90d"`.

### Step 3: Group

**Path and topic modes** — group results by type:

| Section | Types included |
|---|---|
| Rules | `rule` |
| Decisions | `adr` |
| Specs | `spec` |
| Patterns | `cpat` |
| In Progress | `plan` or `idea` with status `draft` |

Drop other types. Results are already sorted by `search_documents` (specificity → type priority → mtime); keep the top 5 per section.

**Pickup mode** — three fixed sections:
- **In Progress** — results from the drafts call
- **Recent Decisions** — `adr` results from the recent-accepted call
- **Recent Rules** — `rule` results from the recent-accepted call

### Step 4: Guide routing

For each item in the Rules, Decisions, or Specs sections, inspect its `incoming_relations`. If a relation of type `implements` or `related` points from a `guide`, inline that guide as an indented bullet under the parent. Skip a guide that is already inlined under a sibling in the same section.

### Step 5: Render

```
## Rules (N)
- **<title>** [rule · <status> · <match.kind>]
  `<path>`
  > <excerpt>
  - 📖 **<guide title>** [guide · <status>]

## Decisions (N)
- **<title>** [adr · <status> · <match.kind>]
  `<path>`
  > <excerpt>

## Specs (N)
...

## Patterns (N)
...

## In Progress (N)
⚠️  **<title>** [plan · draft]
  `<path>`
  > <excerpt>

_Classified as: <mode>._
```

**Do NOT emit a section header if its group is empty.** The classification footer is always emitted.

If all sections are empty, fall through to Step 6.

### Step 6: Empty state

- Call `mcp__archcore__list_documents(limit=1)`. If the knowledge base is empty → "No documents indexed yet. Run `/archcore:capture` or `/archcore:decide` to seed `.archcore/`."
- Otherwise → "No documents reference `<scope>`. Consider using `@<scope>` in a rule or ADR so future work in this area surfaces the context automatically."

## Result

A grouped markdown surface of the rules, ADRs, specs, patterns, and in-progress work that applies to the requested scope — or a pickup summary of draft work + recent accepted decisions and rules when called with no argument. A classification footer identifies which mode was chosen.

Record a decision — finalized (creates ADR, optionally rule + guide) or open proposal for team review (creates RFC). Activate when user says 'we decided', 'record this decision', 'draft an RFC', 'proposing X', 'should we switch to Y'. Do NOT activate for feature planning (use /archcore:plan), documenting existing code (use /archcore:capture), or making a full standard cascade (use /archcore:standard).

# /archcore:decide

Record a decision or a proposal for one. Routes between:

- **Finalized decision** → ADR (optionally followed by rule + guide as a standard)
- **Open proposal** → RFC (for team review before a decision is made)

## When to use

- "Record the decision to use PostgreSQL"
- "We decided to go with microservices"
- "Document why we chose JWT over sessions"
- "Draft an RFC for switching from REST to gRPC"
- "Proposing we adopt feature flags"
- "Should we move to Kubernetes?" (open → RFC)

**Not decide:**

- Planning a feature → `/archcore:plan`
- Making a full standard cascade (ADR → rule → guide) → `/archcore:standard`
- Documenting a component → `/archcore:capture`
- Reading applicable rules/ADRs/specs before coding → `/archcore:context`
- Picking up where work left off → `/archcore:context`

## Routing table

| Signal | Route | Documents |
|---|---|---|
| User describes a **finalized decision** (default) | → adr | Single ADR |
| User describes an **open proposal** ("thinking about", "should we", "proposing") | → rfc | Single RFC |
| User says "and make it a standard" or implies enforcement | → adr + standard-track continuation | ADR, then offer rule + guide |

Default for finalized decisions: create a single ADR. After creation, offer: "Want to codify this into a team standard? (rule + guide)".

## Execution

### Step 1: Check existing

`mcp__archcore__list_documents(types=["adr", "rfc"])` — check for existing decisions or proposals on this topic.

### Step 2: Route

If user language suggests the decision is still open ("thinking about", "should we", "proposing", "design proposal"), confirm with the user: "This sounds like an open proposal — draft an RFC for team review?" If yes, proceed to Step 3b. Otherwise continue with Step 3 (ADR).

### Step 3: Create ADR (finalized decision path)

- Read `skills/_shared/precision-rules.md` and `skills/_shared/adr-contract.md` once before composing. The contract specifies required structure; the rules specify forbidden lexicon and authoring conventions.
- Ask: "What was the decision (specific choice with version/name)? What alternatives were considered, and why was each rejected? What conditions would invalidate this decision?"
- Compose ADR content per the contract: fill Context with one concrete trigger and a code/measurement reference (or `[assumption]` if forward-looking), Decision in one specific sentence, Alternatives Considered with ≥2 named items each carrying an explicit rejection reason, Consequences split into positive + tradeoff with falsifiable claims (or `[expected]`), and Superseded when with ≥2 measurable conditions when feasible. Avoid forbidden lexicon from the rules.
- `mcp__archcore__create_document(type="adr")`

Then continue to Step 4.

### Step 3b: Create RFC (open proposal path)

- Ask: "What change are you proposing? What problem does it solve?"
- Compose content covering Summary, Motivation, Detailed Design, Drawbacks, Alternatives.
- `mcp__archcore__create_document(type="rfc")`
- Suggest relations: rfc `extends` existing ADR (if revising a past decision), or rfc `related` idea (if an idea inspired it).

RFC flow ends here — no rule + guide continuation (those belong to finalized decisions).

### Step 4: Relate (ADR path)

`mcp__archcore__add_relation` — link the ADR to existing RFCs, specs, plans, or other relevant documents.

### Step 5: Offer continuation (ADR path only)

Ask: "Want to codify this into a team standard? I can create a rule (mandatory behavior) and guide (how-to) based on this decision."

**If yes:**

**Rule:**
- Read `skills/_shared/precision-rules.md` if not already loaded.
- Ask: "What are the mandatory behaviors (MUST / MUST NOT statements)? How will each be verified — test, lint, CI signal, or manual review?"
- Compose rule content with imperative directives; provide Rationale, Good/Bad Examples grounded in actual code paths or scenarios, and Enforcement that names the verifier per directive. Avoid forbidden lexicon.
- `mcp__archcore__create_document(type="rule")`
- `mcp__archcore__add_relation` — rule `implements` adr

**Guide:**
- Ask: "What steps should developers follow?"
- Compose content covering Prerequisites, Steps (numbered), Verification, Common Issues.
- `mcp__archcore__create_document(type="guide")`
- `mcp__archcore__add_relation` — guide `related` rule

## Result

Minimum: one ADR or one RFC. Maximum: ADR + rule + guide (the standard chain). Report: paths, relations, recommended next actions.

Advanced — Full feature delivery flow: PRD → spec → plan → task-type. Best for well-scoped features that need formal specification and a repeatable delivery pattern. For lightweight product planning, use /archcore:product-track.

# Feature Track: PRD → spec → plan → task-type

Full feature lifecycle from requirements to repeatable implementation pattern. Best for well-scoped features that need formal specification and a recurring delivery pattern.

## Step 1: Check existing

`mcp__archcore__list_documents(types=["prd", "spec", "plan", "task-type"])` — see what exists. If `$ARGUMENTS` provided, check for duplicates on this topic.

## Step 2: Determine scope

If related documents already exist (e.g., a PRD without a spec), pick up where the chain left off — don't recreate.

## Step 3: PRD

Use the `AskUserQuestion` tool to ask: "What problem does this solve? What are the success metrics?"

Compose content covering Vision, Problem Statement, Goals and Success Metrics, Requirements. Create via `mcp__archcore__create_document(type="prd")`.

## Step 4: Spec

Use the `AskUserQuestion` tool to ask: "What is the technical contract? What is the API surface?"

Compose content covering Purpose, Scope, Authority, Subject, Contract Surface, Normative Behavior, Constraints, Invariants, Error Handling, Conformance. Create via `mcp__archcore__create_document(type="spec")`.

Add relation: `mcp__archcore__add_relation` — spec `implements` prd.

## Step 5: Plan

Use the `AskUserQuestion` tool to ask: "What are the implementation phases? What are the blockers?"

Compose content covering Goal, Tasks (phased), Acceptance Criteria, Dependencies. Create via `mcp__archcore__create_document(type="plan")`.

Add relation: `mcp__archcore__add_relation` — plan `implements` spec.

## Step 6: Task-type

Use the `AskUserQuestion` tool to ask: "What's the recurring implementation pattern? What are the key steps each time?"

Compose content covering Context, Steps, Checklist, Pitfalls. Create via `mcp__archcore__create_document(type="task-type")`.

Add relation: `mcp__archcore__add_relation` — task-type `related` plan.

## Step 7: Relate to existing

Check for ADRs, rules, or other documents that should be linked. Suggest additional `add_relation` calls.

## Result

Four linked documents: PRD → spec → plan → task-type (spec `implements` prd, plan `implements` spec, task-type `related` plan).

Show available Archcore commands and how to use them. Use when onboarding, exploring what skills are available, or when you're not sure which command to run.

# /archcore:help

Guide to what you can do with the Archcore plugin.

## When to use

- "What can I do with Archcore?"
- "Help"
- "What commands are available?"

## Routing table

No routing needed. Single behavior: present the command guide.

## Execution

Present the following guide:

---

## Quick Start

Most users start here. Describe what you need — the system picks the right document types automatically.

| Command | What it does |
|---|---|
| `/archcore:capture [topic]` | Document a module, component, or topic |
| `/archcore:plan [feature]` | Plan a feature end-to-end (idea → PRD → plan) |
| `/archcore:decide [topic]` | Record a technical decision |
| `/archcore:standard [topic]` | Establish a team standard (decision → rule → guide) |
| `/archcore:review` | Dashboard of document counts and stats; `--deep` for a full health audit |
| `/archcore:actualize` | Detect stale docs and suggest updates |

**Tip:** You can also just describe what you need in natural language. Claude will pick the right command automatically.

## Advanced — Multi-Document Flows

For users who know which documentation flow they need:

| Command | Flow |
|---|---|
| `/archcore:product-track [topic]` | idea → PRD → plan |
| `/archcore:sources-track [topic]` | MRD → BRD → URD |
| `/archcore:iso-track [topic]` | BRS → StRS → SyRS → SRS |
| `/archcore:architecture-track [topic]` | ADR → spec → plan |
| `/archcore:standard-track [topic]` | ADR → rule → guide |
| `/archcore:feature-track [topic]` | PRD → spec → plan → task-type |

## Expert — Single Document Types

Create a specific document type directly. These commands are user-only shortcuts (the model routes through Quick Start commands for natural-language requests).

**Knowledge:** `/archcore:adr`, `/archcore:rfc`, `/archcore:rule`, `/archcore:guide`, `/archcore:doc`, `/archcore:spec`

**Vision:** `/archcore:prd`, `/archcore:idea`

**Experience:** `/archcore:task-type`, `/archcore:cpat`

## Hidden — Niche Discovery & ISO 29148 Types

Seven document types are not shown in `/` autocomplete to reduce cognitive load: `mrd`, `brd`, `urd`, `brs`, `strs`, `syrs`, `srs`. The model still knows about them and will reach them when you invoke the right track:

- **Market / business / user requirements (`mrd` / `brd` / `urd`):** use `/archcore:sources-track [topic]`
- **ISO 29148 cascade (`brs` → `strs` → `syrs` → `srs`):** use `/archcore:iso-track [topic]`
- **Direct creation for any type:** call the `mcp__archcore__create_document` tool with `type=<slug>`.

## Setup

If Archcore commands fail with MCP tool errors, the CLI needs to be installed:

1. **Install CLI:** `curl -fsSL https://archcore.ai/install.sh | bash`
2. **Initialize project:** `archcore init`
3. **Restart** the session

The plugin provides skills, agents, and hooks — but document operations (create, update, delete) require the Archcore CLI, which runs the MCP server.

---

## Result

The guide above, presented as-is. No additional commentary needed.

Advanced — Formal ISO 29148 requirements cascade: BRS → StRS → SyRS → SRS. Best for regulated systems, multi-team projects, or complex distributed systems requiring traceable, auditable requirements. For lighter product discovery use /archcore:sources-track.

# ISO 29148 Track: BRS → StRS → SyRS → SRS

Formal requirements decomposition with traceability. Best for regulated systems, multi-team projects, complex distributed systems.

## Step 1: Check existing

`mcp__archcore__list_documents(types=["brs", "strs", "syrs", "srs", "mrd", "brd", "urd"])` — see what exists. If `$ARGUMENTS` provided, check for duplicates on this topic.

## Step 2: Determine scope

If upstream documents exist (MRD, BRD, URD), reference them. If part of the cascade already exists, pick up where it left off.

## Step 3: BRS (Business Requirements Specification)

Use the `AskUserQuestion` tool to ask: "What business goals does this formalize? What source documents exist (MRD, BRD)?"

Compose content covering all BRS sections using source documents for depth. Create via `mcp__archcore__create_document(type="brs")`.

Add relations to sources: `mcp__archcore__add_relation` — brs `implements` mrd/brd (if they exist).

## Step 4: StRS (Stakeholder Requirements Specification)

Use the `AskUserQuestion` tool to ask: "What stakeholder classes exist? What are their distinct requirements?"

Compose content covering all StRS sections using BRS and URD for depth. Create via `mcp__archcore__create_document(type="strs")`.

Add relations:
- strs `implements` brs
- strs `implements` urd (if URD exists)

## Step 5: SyRS (System Requirements Specification)

Use the `AskUserQuestion` tool to ask: "What is the system boundary? What are the key interfaces and operational modes?"

Compose content covering all SyRS sections using StRS for depth. Create via `mcp__archcore__create_document(type="syrs")`.

Add relation: `mcp__archcore__add_relation` — syrs `implements` strs.

## Step 6: SRS (Software Requirements Specification)

Use the `AskUserQuestion` tool to ask: "What software components need specifying? What are the functional and non-functional requirements?"

Compose content covering all SRS sections using SyRS for depth. Create via `mcp__archcore__create_document(type="srs")`.

Add relation: `mcp__archcore__add_relation` — srs `implements` syrs.

## Step 7: Relate to existing

Check for specs, plans, or PRDs that should be linked. SRS typically flows into `spec` or `plan` documents.

## Result

Four cascading documents: BRS → StRS → SyRS → SRS (each `implements` previous). Full ISO 29148 traceability chain.

Plan a feature or initiative — creates a requirements chain (idea → PRD → plan) for large scope, or a single plan document for focused work. Use when someone says 'let's plan', 'create a roadmap for', or 'I need to plan X'. Not for recording a decision — use /archcore:decide.

# /archcore:plan

Plan a feature or initiative. Creates the full requirements chain (idea → PRD → plan) or a single plan document, depending on scope.

## When to use

- "Plan the auth redesign"
- "I need to plan a new notification system"
- "Create a feature plan for the API migration"
- "Let's plan this out"

**Not plan:**
- Recording a decision → `/archcore:decide`
- Documenting existing code → `/archcore:capture`
- Establishing a standard → `/archcore:standard`
- Reading applicable rules/ADRs/specs before coding → `/archcore:context`
- Picking up where work left off → `/archcore:context`

## Routing table

| Signal | Route | Documents |
|---|---|---|
| User describes a **feature or initiative** (default) | → product-track flow | idea → prd → plan |
| User says "just a plan" or "only the plan document" | → single plan | plan only |
| User says "need research first" or "market analysis" | → sources-track then product-track | mrd → brd → urd, then idea → prd → plan |
| Ambiguous | → ask one question | "Full feature plan (idea + PRD + plan) or just a plan document?" |

Default: product-track flow (idea → prd → plan). This is the smallest complete planning unit.

## Execution

### Step 1: Check existing

`mcp__archcore__list_documents(types=["idea", "prd", "plan"])` — check what exists on this topic. If partial chain exists, pick up where it left off.

### Step 2: Scope

If `$ARGUMENTS` is clear, proceed with default (product-track). If ambiguous, ask: "Full feature plan (idea + PRD + plan) or just a plan document?"

### Step 3: Create documents

**If product-track flow (default):**

Skip any documents that already exist on this topic.

**Idea** (if missing):
- Ask: "What's the core concept? Who would benefit?"
- Compose content covering Idea, Value, Possible Implementation, Risks and Constraints.
- `mcp__archcore__create_document(type="idea")`

**PRD** (if missing):
- Ask: "What problem does this solve? What are the success metrics?"
- Compose content covering Vision, Problem Statement, Goals and Success Metrics, Requirements.
- `mcp__archcore__create_document(type="prd")`
- `mcp__archcore__add_relation` — prd `implements` idea

**Plan** (if missing):
- Ask: "What are the key phases? What are the dependencies?"
- Compose content covering Goal, Tasks (phased), Acceptance Criteria, Dependencies.
- `mcp__archcore__create_document(type="plan")`
- `mcp__archcore__add_relation` — plan `implements` prd

**If single plan only:**
- Ask: "What is the goal? What are the key phases and dependencies?"
- Compose content covering Goal, Tasks (phased), Acceptance Criteria, Dependencies.
- `mcp__archcore__create_document(type="plan")`

### Step 4: Relate

Suggest `mcp__archcore__add_relation` calls to link with existing ADRs, specs, or other relevant documents.

## Result

Product-track: three linked documents — idea → prd → plan (each `implements` previous). Single plan: one plan document. Report: paths, relations, recommended next actions (e.g., "consider creating a spec for the technical contract").

Advanced — Lightweight product requirements flow: idea → PRD → plan. Best for individual features, small teams, or rapid prototyping. For engineer-led feature delivery use /archcore:feature-track; for ISO requirements cascade use /archcore:iso-track.

# Product Track: idea → PRD → plan

Lightweight requirements flow. Best for individual features, small teams, rapid prototyping.

## Step 1: Check existing

`mcp__archcore__list_documents(types=["idea", "prd", "plan"])` — see what exists. If `$ARGUMENTS` provided, check for duplicates on this topic.

## Step 2: Determine scope

If related documents already exist (e.g., an idea without a PRD), pick up where the chain left off — don't recreate.

## Step 3: Idea

Use the `AskUserQuestion` tool to ask: "What's the core concept? Who would benefit?"

Compose content covering Idea, Value, Possible Implementation, Risks and Constraints. Create via `mcp__archcore__create_document(type="idea")`.

## Step 4: PRD

Use the `AskUserQuestion` tool to ask: "What problem does this solve? What are the success metrics?"

Compose content covering Vision, Problem Statement, Goals and Success Metrics, Requirements. Create via `mcp__archcore__create_document(type="prd")`.

Add relation: `mcp__archcore__add_relation` — prd `implements` idea.

## Step 5: Plan

Use the `AskUserQuestion` tool to ask: "What are the key phases? What are the dependencies?"

Compose content covering Goal, Tasks (phased), Acceptance Criteria, Dependencies. Create via `mcp__archcore__create_document(type="plan")`.

Add relation: `mcp__archcore__add_relation` — plan `implements` prd.

## Step 6: Relate to existing

Check for ADRs, specs, or other documents that should be linked. Suggest additional `add_relation` calls.

## Result

Three linked documents: idea → prd → plan (each `implements` previous).

Review documentation health. Default: compact dashboard (counts, status breakdown, relations, orphans). With --deep: full audit with coverage gaps, staleness, relation health, and prioritized recommendations. Activate when user asks 'show status', 'how many docs', 'dashboard', 'review the docs', 'audit the knowledge base', 'documentation gaps'. For code-drift detection use /archcore:actualize.

# /archcore:review

Review Archcore documentation health. Default mode is a compact dashboard; `--deep` runs a full audit with prioritized recommendations.

## When to use

- "Show status" / "How many docs do we have?" / "Dashboard" → default short mode
- "Review the docs" / "Audit the knowledge base" / "Documentation gaps?" → `--deep`

**Not review:**
- Creating new documentation → `/archcore:capture`, `/archcore:plan`, `/archcore:decide`
- Reading applicable rules/ADRs/specs before coding → `/archcore:context`
- Picking up where work left off → `/archcore:context`
- Stale docs after code drift → `/archcore:actualize`

## Routing table

| Signal | Mode | Scope |
|---|---|---|
| No arguments | → short dashboard | All documents |
| `--deep` | → full audit | All documents |
| `--deep <category\|tag\|type>` | → full audit, filtered | Filter applied |
| `<category\|tag\|type>` (no `--deep`) | → full audit, filtered | Same as `--deep <filter>` |

The dashboard is project-wide by design — it doesn't take filters. Any non-flag argument implies the user wants more than counts, so route to deep mode.

## Execution

### Step 1: Gather data

Call `mcp__archcore__list_documents` and `mcp__archcore__list_relations`. If a filter argument is present, apply it in-memory to the document list before analysis.

### Step 2 (short mode — default): Present dashboard

Output the four tables, then a one-line issues summary. Data only, no analysis.

**Documents by Category**

| Category | Count |
|---|---|
| Vision | _n_ |
| Knowledge | _n_ |
| Experience | _n_ |
| **Total** | _n_ |

**Documents by Status**

| Status | Count |
|---|---|
| draft | _n_ |
| accepted | _n_ |
| rejected | _n_ |

**Documents by Type** — list each type with count, skip types with 0.

**Relations**

| Type | Count |
|---|---|
| related | _n_ |
| implements | _n_ |
| extends | _n_ |
| depends_on | _n_ |

**Issues** — orphaned documents (no relations), high draft count. One line each, no explanations.

End with: _For a full audit with recommendations, run `/archcore:review --deep`._

### Step 2 (deep mode — `--deep` or any non-flag arg): Analyze and report

Check for:

**Coverage gaps:**
- ADRs without rules/guides (decisions not codified)
- PRDs without plans (requirements without implementation path)
- Rules without guides (standards without instructions)
- Empty categories or types with zero documents

**Staleness:**
- Documents stuck in `draft` that may need `accepted` or `rejected`
- Documents with stale content indicators

**Relation health:**
- Orphaned documents (no incoming or outgoing relations)
- Plans without `implements` to a PRD
- Specs without `implements` to requirements
- Broken chains (ISO cascade with gaps)

**Tag hygiene:**
- Tags used only once (potential inconsistency)
- Related documents with different tags

Report with these sections:

1. **Overview** — totals by category and status
2. **Gaps** — missing documents or relations with specific recommendations
3. **Staleness** — documents needing attention
4. **Orphans** — documents with no relations
5. **Actions** — prioritized list of fixes, most impactful first

## Result

Short mode: compact dashboard, data only. Deep mode: actionable report with prioritized fixes — findings and recommendations only, no verbose analysis.

Advanced — Discovery requirements flow: MRD (market) → BRD (business) → URD (user). Best for product teams doing research, stakeholder alignment, or business analysis before committing to a product. Not for technical requirements — use /archcore:iso-track.

# Sources Track: MRD → BRD → URD

Discovery-focused flow. Best for product teams doing research, stakeholder alignment, business analysis.

## Step 1: Check existing

`mcp__archcore__list_documents(types=["mrd", "brd", "urd", "prd"])` — see what exists. If `$ARGUMENTS` provided, check for duplicates on this topic.

## Step 2: Determine scope

If related documents already exist, pick up where the chain left off. All three source documents are peer-level — order is flexible, but MRD → BRD → URD is the recommended sequence.

## Step 3: MRD (Market Requirements)

Use the `AskUserQuestion` tool to ask: "What market are you analyzing? What's the key opportunity?"

Compose content covering Market Landscape, TAM/SAM/SOM, Competitive Analysis, Market Needs, Opportunity and Timing. Create via `mcp__archcore__create_document(type="mrd")`.

## Step 4: BRD (Business Requirements)

Use the `AskUserQuestion` tool to ask: "What are the business objectives? What's the expected ROI?"

Compose content covering Business Objectives, Stakeholders, Business Rules, Success Metrics and ROI, Dependencies. Create via `mcp__archcore__create_document(type="brd")`.

Add relation: `mcp__archcore__add_relation` — brd `related` mrd (peer source documents).

## Step 5: URD (User Requirements)

Use the `AskUserQuestion` tool to ask: "Who are the users? What are their key needs?"

Compose content covering User Personas, User Journeys, User Requirements, Usability Requirements, Acceptance Criteria. Create via `mcp__archcore__create_document(type="urd")`.

Add relations:
- urd `related` mrd
- urd `related` brd

## Step 6: Next steps

Sources feed into product decisions. Suggest:
- Create a **PRD** informed by all three sources (Product Track)
- Or formalize into **BRS** to start the ISO 29148 cascade
- Link with `related` to any existing PRD, or `implements` to BRS.

## Result

Three peer source documents: MRD + BRD + URD, linked as `related`. Ready to feed into PRD or BRS.

Advanced — Create an ADR → (optional CPAT) → rule → guide cascade to codify a team standard. Activate when user explicitly requests a standard cascade or a full 'decision to enforcement' chain. For a single decision without enforcement, use /archcore:decide; for mixed intent routing, use /archcore:standard.

# Standard Track: ADR → (optional CPAT) → rule → guide

Establishes a team standard from decision to enforceable rule to practical how-to. Best for codifying technical decisions into mandatory practices. If the decision represents a code-pattern shift (before/after), a CPAT is offered between ADR and rule.

## Step 1: Check existing

`mcp__archcore__list_documents(types=["adr", "cpat", "rule", "guide"])` — see what exists. If `$ARGUMENTS` provided, check for duplicates on this topic.

## Step 2: Determine scope

If related documents already exist (e.g., an ADR without a rule), pick up where the chain left off — don't recreate.

## Step 3: ADR

Use the `AskUserQuestion` tool to ask: "What decision was made? Why this approach over alternatives?"

Compose content covering Context, Decision, Alternatives Considered, Consequences. Create via `mcp__archcore__create_document(type="adr")`.

## Step 3b: CPAT (optional)

Offer only if the decision clearly represents a code-pattern change (refactor, code-style shift, idiom migration). Otherwise skip to Step 4.

Ask: "Does this decision represent a code-pattern change (before/after code shift)? If yes, I can document the pattern as a CPAT."

If yes:

- Ask: "What pattern changed? Show the before and after."
- Compose content covering What Changed, Why, Before, After, Scope. Create via `mcp__archcore__create_document(type="cpat")`.
- Add relation: `mcp__archcore__add_relation` — cpat `implements` adr.

## Step 4: Rule

Use the `AskUserQuestion` tool to ask: "What are the mandatory behaviors? How should this be enforced?"

Compose content covering Rule (imperative statements), Rationale, Examples (Good/Bad), Enforcement. Create via `mcp__archcore__create_document(type="rule")`.

Add relation: `mcp__archcore__add_relation` — rule `implements` adr.

If a CPAT was created in Step 3b, also add: `mcp__archcore__add_relation` — rule `related` cpat.

## Step 5: Guide

Use the `AskUserQuestion` tool to ask: "What steps should developers follow? What are common pitfalls?"

Compose content covering Prerequisites, Steps (numbered), Verification, Common Issues. Create via `mcp__archcore__create_document(type="guide")`.

Add relation: `mcp__archcore__add_relation` — guide `related` rule.

## Step 6: Relate to existing

Check for specs, plans, or other documents that should be linked. Suggest additional `add_relation` calls.

## Result

Three or four linked documents: ADR → [optional CPAT] → rule → guide. Relations: rule `implements` adr, guide `related` rule, and if CPAT exists: cpat `implements` adr, rule `related` cpat.

Establish a team standard end-to-end — creates ADR → rule → guide chain for codifying practices. Activate when user says 'make this a standard', 'establish a convention', 'codify this practice'. Do NOT activate for recording a one-off decision (use /archcore:decide) or feature planning (use /archcore:plan).

# /archcore:standard

Establish a team standard. Creates the full chain: ADR (why this standard) → rule (mandatory behavior) → guide (how to follow it).

## When to use

- "Make this a team standard"
- "We need a coding convention for error handling"
- "Standardize how we do API versioning"
- "Create a standard for database migrations"

**Not standard:**
- Recording a decision without enforcement → `/archcore:decide`
- Planning a feature → `/archcore:plan`
- Documenting existing behavior → `/archcore:capture`
- Reading applicable rules/ADRs/specs before coding → `/archcore:context`
- Picking up where work left off → `/archcore:context`

## Routing table

| Signal | Route | Documents |
|---|---|---|
| User wants a **new standard** (default) | → full chain | adr → rule → guide |
| ADR already exists on this topic | → pick up from rule | rule → guide (link to existing ADR) |
| User says "just a rule" or "skip the ADR" | → rule + guide only | rule + guide |

Default: full standard-track chain (adr → rule → guide).

## Execution

### Step 1: Check existing

`mcp__archcore__list_documents(types=["adr", "rule", "guide"])` — check what exists on this topic. If ADR exists, skip to rule. If rule exists, skip to guide.

### Step 2: Create documents

Skip any documents that already exist on this topic.

**ADR** (if missing):
- Ask: "What decision led to this standard? What alternatives were considered?"
- Compose content covering Context, Decision, Alternatives Considered, Consequences.
- `mcp__archcore__create_document(type="adr")`

**Rule:**
- Ask: "What are the mandatory behaviors? How should this be enforced?"
- Compose content covering Rule (imperative statements), Rationale, Examples (Good/Bad), Enforcement.
- `mcp__archcore__create_document(type="rule")`
- `mcp__archcore__add_relation` — rule `implements` adr

**Guide:**
- Ask: "What steps should developers follow? What are common pitfalls?"
- Compose content covering Prerequisites, Steps (numbered), Verification, Common Issues.
- `mcp__archcore__create_document(type="guide")`
- `mcp__archcore__add_relation` — guide `related` rule

### Step 3: Relate

Suggest `mcp__archcore__add_relation` calls to link with existing specs, plans, or other standards.

## Result

Three linked documents: ADR → rule → guide (rule `implements` adr, guide `related` rule). Report: paths, relations, recommended next actions.

Run plugin integrity checks — validates configs, scripts, skills, hooks, agents, and runs test suite.

# /archcore:verify

Comprehensive plugin integrity verification. Run after structural changes to the plugin.

## When to use

- After modifying bin/ scripts, hooks, skills, agents, rules, or JSON configs
- Before creating a pull request
- After merging upstream changes
- When something seems broken

## Execution

### Step 1: Run automated test suite

Run the test suite using Bash:

```
make test
```

If bats-core is not installed, install it first: `brew install bats-core` (macOS) or `apt install bats` (Linux).

Report: total tests, passed, failed. If any fail, list the failed test names and investigate.

### Step 2: Run ShellCheck (if available)

```
make lint
```

If shellcheck is not installed, skip this step and note it.

### Step 3: JSON config quick-check

```
make check-json
```

### Step 4: Manual cross-reference verification

Only if tests pass. Check these items that automated tests may not fully cover:

1. **README accuracy**: Verify the skill count, agent count, and hook count in README.md match reality:
   - Count skills: `ls -d skills/*/SKILL.md | wc -l`
   - Count agents: `ls agents/*.md | wc -l`
   - Compare with numbers stated in README.md

2. **Archcore docs consistency**: If `.archcore/` documents describe plugin components (component-registry.doc.md, plugin-architecture.spec.md), spot-check that they reflect current state.

3. **MCP server availability**: Run `mcp__archcore__list_documents()` to verify MCP tools are functional. If it errors, report the error.

### Step 5: Live hook smoke test (optional)

If the user wants a deeper check:

1. Try writing to a `.archcore/*.md` file using the Write tool — it should be **blocked** by the PreToolUse hook.
2. Create a test document using `mcp__archcore__create_document` — the PostToolUse hook should validate afterward.

## Output Format

Present results as:

```
## Plugin Verification Report

| Phase | Status | Details |
|-------|--------|---------|
| Test suite (N tests) | PASS/FAIL | X passed, Y failed |
| ShellCheck | PASS/SKIP | clean or N warnings |
| JSON configs | PASS/FAIL | all valid or which failed |
| Cross-references | PASS/WARN | any mismatches found |
| MCP tools | PASS/FAIL | functional or error |

**Result: X/Y phases passed.**
```

If any phase fails, list specific issues as action items.

Event hooks configuration

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/session-start"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-archcore-write",
            "timeout": 1
          },
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-code-alignment",
            "timeout": 1
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "mcp__archcore__create_document|mcp__archcore__update_document|mcp__archcore__remove_document|mcp__archcore__add_relation|mcp__archcore__remove_relation",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/validate-archcore",
            "timeout": 3
          }
        ]
      },
      {
        "matcher": "mcp__archcore__update_document",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-cascade",
            "timeout": 3
          }
        ]
      },
      {
        "matcher": "mcp__archcore__create_document|mcp__archcore__update_document",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-precision",
            "timeout": 3
          }
        ]
      }
    ]
  }
}

Archcore knowledge base context — document types, MCP tools, and conventions for working with .archcore/ documents

# Archcore — Git-native context for AI coding agents

You have Archcore MCP tools available for managing the `.archcore/` knowledge base.

## MCP Tools

- `list_documents` — query documents by type, status, category, tags
- `get_document` — read full content + metadata + relations
- `create_document` — create new document with validation and templating
- `update_document` — modify existing document
- `remove_document` — delete document and clean up relations
- `add_relation` — link two documents (related, implements, extends, depends_on)
- `remove_relation` — unlink documents
- `list_relations` — query the relation graph

## Document Types

**Knowledge:** adr (decisions), rfc (proposals), rule (standards), guide (how-tos), doc (reference), spec (contracts)
**Vision:** prd (requirements), idea (concepts), plan (action plans), mrd, brd, urd, brs, strs, syrs, srs
**Experience:** task-type (recurring patterns), cpat (code pattern changes)

## Critical Rule

All `.archcore/` document operations MUST go through MCP tools. Never write directly to `.archcore/*.md` files — use `create_document`, `update_document`, or `remove_document` instead. This ensures validation, templates, and the sync manifest stay consistent.