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.

# 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.

# 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:status`
- Creating new documentation → `/archcore:capture`, `/archcore:plan`

## 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.

Records architectural decisions with context, alternatives, and consequences. Activates for finalized technical decisions, technology choices, or trade-off discussions.

# ADR — Architecture Decision Record

## When to use

- A technical decision has been finalized
- Recording why a specific approach was chosen over alternatives

**Not ADR:**

- Still discussing → **rfc**
- Mandatory standard → **rule**
- How-to instructions → **guide**

## Quick create

1. `mcp__archcore__list_documents(types=["adr"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What was the decision? What alternatives were considered?"
3. Compose content covering Context, Decision, Alternatives Considered, Consequences — using user's answers for depth. Pass as `content` parameter to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type         | Target     | When                      |
| --------- | ------------ | ---------- | ------------------------- |
| Incoming  | `implements` | plan, spec | Implements this decision  |
| Outgoing  | `related`    | rule       | Codifies this decision    |
| Outgoing  | `related`    | guide      | Explains how to follow it |

**Flows:** RFC → **ADR** → rule → guide

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).

Expert — Documents business requirements, objectives, and ROI to justify a project. Activates when making a business case or documenting ROI expectations — e.g., 'business case for X', 'justify this project', 'business requirements document'.

# BRD — Business Requirements Document

## When to use

- Justifying a project from a business perspective
- Documenting business objectives and ROI expectations

**Not BRD:**

- Market analysis → **mrd**
- User needs → **urd**
- Product scope → **prd**

## Quick create

1. `mcp__archcore__list_documents(types=["brd", "mrd", "urd"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What are the business objectives? What's the expected ROI?"
3. Compose content covering Business Objectives, Stakeholders, Business Rules, Success Metrics and ROI, Dependencies — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type            | Target   | When                             |
| --------- | --------------- | -------- | -------------------------------- |
| Outgoing  | `implements` by | BRS      | Formal business requirements     |
| Peer      | `related`       | MRD, URD | Peer source documents            |
| Outgoing  | `related`       | PRD      | Business context informs product |

**Flows:** MRD+**BRD**+URD → PRD; **BRD** → BRS

Expert — Formalizes business requirements into a traceable specification per ISO 29148. Activates when converting informal business requirements into structured, auditable specs, or starting an ISO 29148 cascade. Use /archcore:brd for informal business cases.

# BRS — Business Requirements Specification (ISO 29148)

## When to use

- Formalizing business requirements from MRD/BRD into traceable specs
- Starting the ISO 29148 requirements cascade

**Not BRS:**
- Informal business case → **brd**
- Product requirements → **prd**
- Stakeholder requirements → **strs** (next level)

## Quick create

1. `mcp__archcore__list_documents(types=["brs", "brd", "mrd"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What business goals does this formalize? What source documents exist?"
3. Compose content covering all BRS sections — using user's answers and source documents for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` — typically `implements` BRD/MRD.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `implements` | MRD or BRD | Formalizes informal requirements |
| Outgoing | `implements` by | StRS | Next level in cascade |

**Flows:** MRD/BRD → **BRS** → StRS → SyRS → SRS

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`

## 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").

Expert — Documents a code pattern change with before/after examples and migration scope. Activates when a coding pattern has changed — e.g., 'we switched from X to Y', 'document this refactor pattern', 'before/after code change'. For deciding to change, use /archcore:adr.

# CPAT — Code Pattern Change

## When to use

- The team has decided to change a coding pattern
- Recording a before/after code shift with scope

**Not CPAT:**
- Deciding whether to change → **adr**
- Defining the new standard → **rule**
- Step-by-step migration → **guide**

## Quick create

1. `mcp__archcore__list_documents(types=["cpat", "adr", "rule"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What pattern changed? Show the before and after."
3. Compose content covering What Changed, Why, Before, After, Scope — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `implements` | ADR | Implements decision to change |
| Outgoing | `extends` | rule | Elaborates with before/after |
| Peer | `related` | rule | New standard being adopted |

**Flows:** ADR → **CPAT** + rule

Record a finalized technical or architectural decision — creates ADR, optionally codifies into rule + guide. Activate when user says 'we decided', 'record this decision', 'capture why we chose X'. Do NOT activate for open proposals (use /archcore:rfc), feature planning (use /archcore:plan), or documenting existing code (use /archcore:capture).

# /archcore:decide

Record a decision. Creates an ADR (Architecture Decision Record) and optionally offers to codify it into a team standard (rule + guide).

## When to use

- "Record the decision to use PostgreSQL"
- "We decided to go with microservices"
- "Document why we chose JWT over sessions"
- "Let's capture this decision"

**Not decide:**
- Planning a feature → `/archcore:plan`
- Making a standard → `/archcore:standard` (use this if you already know it should become a rule)
- Documenting a component → `/archcore:capture`
- Still discussing, no decision yet → use `/archcore:rfc` directly

## Routing table

| Signal | Route | Documents |
|---|---|---|
| User describes a **finalized decision** (default) | → adr | Single ADR |
| User says "and make it a standard" or implies enforcement | → adr + standard-track continuation | ADR, then offer rule + guide |
| Still discussing, not decided | → redirect to rfc | Suggest `/archcore:rfc` instead |

Default: create a single ADR. After creation, always 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 on this topic.

### Step 2: Route

If user language suggests the decision is still open ("thinking about", "should we", "proposal"), suggest `/archcore:rfc` instead and stop. Otherwise proceed with ADR.

### Step 3: Create ADR

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

### Step 4: Relate

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

### Step 5: Offer continuation

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:**
- 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?"
- 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. Maximum: ADR + rule + guide (the standard-track chain). Report: paths, relations, recommended next actions.

Expert — Creates reference material: glossaries, registries, API catalogues, or lookup tables. Activates when creating reference content someone would look up, not follow or enforce — e.g., 'create a glossary', 'document our service list', 'catalog the APIs'.

# Doc — Reference Material

## When to use

- Creating a glossary, registry, or lookup table
- Cataloging services, APIs, or components

**Not Doc:**
- Mandatory standard → **rule**
- Step-by-step procedure → **guide**
- Normative contract → **spec**

## Quick create

1. `mcp__archcore__list_documents(types=["doc"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What reference material are you cataloging? Who is it for?"
3. Compose content covering Overview, Content (tables/lists), Examples — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Peer | `related` | rule | Doc lists things, rule governs them |
| Peer | `related` | guide | Doc catalogs, guide instructs |

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).

Render the Archcore document graph as a Mermaid flowchart grouped by category, with relation styles and an orphan list. Activate when user asks to 'show the graph', 'visualize the docs', 'render the relation map', or 'draw the docs graph'. Do NOT activate for narrative health audits (use /archcore:review), counts-only dashboards (use /archcore:status), or staleness detection (use /archcore:actualize).

# /archcore:graph

Visualize the Archcore knowledge base as a Mermaid flowchart with grouped nodes, styled edges per relation type, and a separate orphan list.

## When to use

- "Show me the document graph"
- "Render the relation map"
- "Visualize the knowledge base"
- "Draw the docs graph for [tag/type/doc]"

**Not graph:**

- Narrative health audit with recommendations → `/archcore:review`
- Compact counts dashboard → `/archcore:status`
- Staleness/drift detection → `/archcore:actualize`

## Routing table

| Signal                                | Scope                                | Filter                                                                         |
| ------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------ |
| No arguments                          | full graph                           | all documents, all relations                                                   |
| Tag name (`auth`, `payments`)         | tag-scoped subgraph                  | documents having the tag + their relations                                     |
| Type identifier (`adr`, `prd`, ...)   | type-scoped subgraph                 | documents of that type + their relations                                       |
| Category (`vision`, `knowledge`, `experience`) | category-scoped subgraph     | documents in that category                                                     |
| Document slug (matches an existing path) | 1-hop neighborhood              | the document + everything it relates to or is related from                     |
| Ambiguous                             | ask one scope question               | "Graph the full set, or filter by tag/type/category/slug?"                     |

Default: full graph.

## Execution

### Step 1: Gather

Call in parallel:

- `mcp__archcore__list_documents` (apply type/category filter from `$ARGUMENTS` when possible)
- `mcp__archcore__list_relations`

If the filter is a tag or slug, fetch the full document list first, then filter in-memory.

### Step 2: Build the Mermaid diagram

Compose a `flowchart LR` Mermaid block:

1. **Subgraphs per category** — one `subgraph vision`, one `subgraph knowledge`, one `subgraph experience`. Skip empty categories.
2. **Node label** — `<type>: <slug>` (e.g., `adr: jwt-strategy`). Keep labels short — the full title can be added as Mermaid `click` annotation if useful.
3. **Edge styles by relation type**:
   - `implements`  → `-->` (solid arrow)
   - `depends_on`  → `-.->` (dashed arrow)
   - `extends`     → `==>` (thick arrow)
   - `related`     → `---` (plain line, no direction semantics)
4. **Node IDs** — use `<type>_<slug>` with non-alphanumeric characters replaced by `_`. This must be a valid Mermaid id.
5. **Quoting** — wrap labels with spaces or colons in double quotes: `adr_jwt["adr: JWT Strategy"]`.

Example output frame:

```mermaid
flowchart LR
  subgraph vision
    prd_auth["prd: auth-redesign"]
    plan_auth["plan: auth-plan"]
  end
  subgraph knowledge
    adr_jwt["adr: jwt-strategy"]
    rule_tokens["rule: token-handling"]
  end
  plan_auth -->|implements| prd_auth
  plan_auth -.->|depends_on| adr_jwt
  rule_tokens ==>|extends| adr_jwt
```

### Step 3: List orphans

Below the diagram, list documents that have zero outgoing and zero incoming relations in the filtered set:

```
## Orphans (no relations)
- knowledge: component-registry — `.archcore/plugin/component-registry.doc.md`
- vision: release-notes — `.archcore/release-notes.plan.md`
```

If there are none, state: "No orphans in this view."

### Step 4: Summary stats

Add a compact footer:

```
## Summary
- Nodes: N (vision M, knowledge K, experience L)
- Edges: implements=A, depends_on=B, extends=C, related=D
- Largest component: P nodes
- Orphans: Q
```

If filtered, prefix with the filter: "Filtered to tag=`auth` — ...".

### Step 5: Offer next actions

After the output, suggest:

- `/archcore:review` to audit orphans and missing relations
- `/archcore:actualize [slug]` to check code-doc drift for a specific document
- Re-invoke `/archcore:graph <slug>` to focus on a neighborhood

## Result

A Mermaid flowchart block (rendered in supporting UIs as an interactive diagram, shown as code otherwise), an orphan list, and summary stats. Read-only — no documents are created or modified.

Provides step-by-step instructions for completing a specific task with prerequisites and verification. Activates for how-to procedures, setup instructions, or runbooks.

# Guide — How-To Instructions

## When to use

- Documenting a procedure someone needs to follow
- Writing runbooks or onboarding instructions

**Not Guide:**
- Mandatory standard → **rule**
- Reference lookup → **doc**
- Recording a decision → **adr**

## Quick create

1. `mcp__archcore__list_documents(types=["guide", "rule"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What task does this guide help complete? What prerequisites?"
3. Compose content covering Prerequisites, Steps (numbered), Verification, Common Issues — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `depends_on` | rule | Rule this guide helps implement |
| Outgoing | `related` | ADR | Decision context behind procedure |

**Flows:** ADR → rule → **Guide**

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` | Check documentation health and find gaps |
| `/archcore:status` | Quick dashboard of document counts and stats |
| `/archcore:actualize` | Detect stale docs and suggest updates |
| `/archcore:graph [filter]` | Render the document relation graph (Mermaid) |

**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.

Expert — Captures product or technical concepts worth exploring before commitment. Activates for brainstorming, "what if" discussions, or early-stage concept exploration.

# Idea — Concept Exploration

## When to use

- Capturing a concept during brainstorming
- Recording a "what if" that deserves later exploration

**Not Idea:**

- Ready to commit → **prd**
- Technical proposal needing review → **rfc**
- Decision already made → **adr**

## Quick create

1. `mcp__archcore__list_documents(types=["idea"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What's the core concept? Who would benefit?"
3. Compose content covering Idea, Value, Possible Implementation, Risks and Constraints — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type            | Target      | When                         |
| --------- | --------------- | ----------- | ---------------------------- |
| Outgoing  | `implements` by | PRD         | Formalized into requirements |
| Outgoing  | `implements` by | RFC         | Developed into a proposal    |
| Peer      | `related`       | other ideas | Related concepts             |

**Flows:** **Idea** → PRD → plan; **Idea** → RFC → ADR

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.

Expert — Documents market analysis, competitive positioning, and market sizing (TAM/SAM/SOM). Activates when analyzing a market before defining a product — e.g., 'market research', 'competitive analysis', 'market opportunity document'.

# MRD — Market Requirements Document

## When to use

- Analyzing a market before defining a product
- Documenting competitive landscape and market sizing

**Not MRD:**
- Business justification → **brd**
- User needs → **urd**
- Product requirements → **prd**

## Quick create

1. `mcp__archcore__list_documents(types=["mrd", "brd", "urd"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What market are you analyzing? What's the key opportunity?"
3. Compose content covering Market Landscape, TAM/SAM/SOM, Competitive Analysis, Market Needs, Opportunity and Timing — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `implements` by | BRS | Formal requirements from market |
| Peer | `related` | BRD, URD | Peer source documents |
| Outgoing | `related` | PRD | Market context informs product |

**Flows:** **MRD**+BRD+URD → PRD; **MRD** → BRS → StRS → SyRS → SRS

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`

## 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").

Defines product requirements with vision, goals, and success metrics. Activates for product scoping, feature definitions, or when establishing what to build and why.

# PRD — Product Requirements Document

## When to use

- Defining requirements for a new product or major feature
- Establishing goals and success metrics before implementation

**Not PRD:**
- Market analysis → **mrd**
- Business justification → **brd**
- User needs → **urd**
- Formal software spec → **srs**
- Informal concept → **idea**

## Quick create

1. `mcp__archcore__list_documents(types=["prd", "idea"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What problem are you solving? What are the success metrics?"
3. Compose content covering Vision, Problem Statement, Goals and Success Metrics, Requirements — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Incoming | `implements` | idea | PRD formalizes an idea |
| Incoming | `related` | MRD, BRD, URD | Sources inform PRD |
| Outgoing | `implements` by | plan, spec | Implements requirements |

**Flows:** idea → **PRD** → plan; MRD+BRD+URD → **PRD**

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).

Audit documentation health — finds coverage gaps, stale statuses, orphaned documents, and missing relations. Use when you want a full health report with recommendations. For quick counts use /archcore:status; for code-drift detection use /archcore:actualize.

# /archcore:review

Review Archcore documentation health. Finds gaps, stale documents, orphaned relations, and produces actionable recommendations.

## When to use

- "Review the docs"
- "Check documentation health"
- "Are there any documentation gaps?"
- "Audit the knowledge base"

**Not review:**
- Quick counts and stats → `/archcore:status`
- Creating new documentation → `/archcore:capture`, `/archcore:plan`, `/archcore:decide`

## Routing table

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

Default: full review of all documents.

## Execution

### Step 1: Gather data

Call `mcp__archcore__list_documents` and `mcp__archcore__list_relations` to get the full inventory. If `$ARGUMENTS` provided, apply as filter.

### Step 2: Analyze

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

### Step 3: Report

Present a concise summary:

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

Actionable review report with prioritized fixes. No verbose analysis — findings and recommendations only.

Expert — Proposes a significant technical change for team review before a decision is finalized. Activates when proposing a design, exploring a change that needs buy-in, or when the user says 'draft an RFC', 'design proposal', or 'let's get feedback before deciding'.

# RFC — Request for Comments

## When to use

- Proposing a significant technical change that needs buy-in
- Exploring a design that affects multiple systems

**Not RFC:**
- Decision already made → **adr**
- Informal concept → **idea**
- Defining a standard → **rule**

## Quick create

1. `mcp__archcore__list_documents(types=["rfc", "adr"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What change are you proposing? What problem does it solve?"
3. Compose content covering Summary, Motivation, Detailed Design, Drawbacks, Alternatives — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `extends` | existing ADR | Revising a past decision |
| Outgoing | `related` | ADR | ADR recorded after approval |
| Incoming | `related` | idea | Idea that inspired this |

**Flows:** idea → **RFC** → ADR

Defines mandatory team standards and required behaviors with rationale and examples. Activates for coding conventions, enforceable practices, or standards codified from decisions.

# Rule — Team Standard

## When to use

- Defining a mandatory coding standard or convention
- Codifying a decision (ADR) into an enforceable practice

**Not Rule:**
- Recording a decision → **adr**
- Step-by-step instructions → **guide**
- Reference material → **doc**

## Quick create

1. `mcp__archcore__list_documents(types=["rule", "adr"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What must the team always/never do? What motivated this standard?"
3. Compose content covering Rule (imperative statements), Rationale, Examples (Good/Bad), Enforcement — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Incoming | `implements` | ADR | Decision that led to this rule |
| Outgoing | `related` | guide | How to follow this rule |
| Outgoing | `related` | spec | Formalizes this rule's scope |

**Flows:** ADR → **Rule** → guide

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.

Expert — Defines a normative technical contract for a system, API, or interface. Activates when specifying behavioral guarantees, API contracts, or interface protocols — e.g., 'write a spec for', 'define the interface', 'document what this component must do'.

# Spec — Technical Specification

## When to use

- Defining an API contract, interface, or protocol
- Specifying behavioral guarantees for a component

**Not Spec:**
- Team standard for people → **rule**
- Reference lookup → **doc**
- Requirements (what to build) → **srs** or **prd**

## Quick create

1. `mcp__archcore__list_documents(types=["spec", "prd", "srs"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What system/component/interface is being specified?"
3. Compose content covering Purpose, Scope, Authority, Subject, Contract Surface, Normative Behavior, Constraints, Invariants, Error Handling, Conformance — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `implements` | PRD or SRS | Formalizes requirements |
| Outgoing | `depends_on` | ADR | Depends on decisions |
| Peer | `related` | rule | Overlapping governance |

**Flows:** PRD/SRS → **Spec**; ADR → **Spec**

Expert — Formalizes software requirements per ISO 29148 — detailed functional and non-functional requirements for a software system. Activates after SyRS in an ISO 29148 cascade, or standalone when formal software requirements specification is needed. For a technical API contract, use /archcore:spec.

# SRS — Software Requirements Specification (ISO 29148)

## When to use

- Translating system requirements (SyRS) into software-specific specs
- Defining detailed functional and non-functional software requirements

**Not SRS:**
- System-level → **syrs** (one level up)
- Informal product requirements → **prd**
- Technical contract for existing component → **spec**

## Quick create

1. `mcp__archcore__list_documents(types=["srs", "syrs"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What software is being specified? What SyRS does this implement?"
3. Compose content covering all SRS sections — using user's answers and upstream documents for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` — typically `implements` SyRS.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `implements` | SyRS | Formalizes system requirements |
| Outgoing | `implements` by | spec, plan | Realizes SRS requirements |

**Flows:** SyRS → **SRS** → spec/plan

Advanced — Create an ADR → 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 → rule → guide

Establishes a team standard from decision to enforceable rule to practical how-to. Best for codifying technical decisions into mandatory practices.

## Step 1: Check existing

`mcp__archcore__list_documents(types=["adr", "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 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.

## 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 linked documents: ADR → rule → guide (rule `implements` adr, guide `related` rule).

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`

## 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.

Show a compact Archcore dashboard — document counts, status breakdown, relation stats. Activate when user asks 'how many docs', 'show status', 'dashboard'. Do NOT activate for health audits with recommendations (use /archcore:review) or staleness detection (use /archcore:actualize).

# /archcore:status

Quick dashboard of your Archcore knowledge base. Compact numbers, no analysis.

## When to use

- "Show status"
- "How many docs do we have?"
- "Dashboard"

**Not status:**
- Detailed health review with recommendations → `/archcore:review`

## Routing table

No routing needed. Single behavior: gather data, present dashboard.

## Execution

### Step 1: Gather

Call `mcp__archcore__list_documents` and `mcp__archcore__list_relations`.

### Step 2: Present

**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.

## Result

Compact dashboard. Data only, no analysis. For deeper review use `/archcore:review`.

Expert — Formalizes stakeholder requirements per ISO 29148 by decomposing BRS into stakeholder-specific specs. Activates when multiple stakeholder groups have different requirement sets, or progressing through an ISO 29148 cascade after BRS. Use /archcore:urd for informal user needs.

# StRS — Stakeholder Requirements Specification (ISO 29148)

## When to use

- Decomposing BRS into stakeholder-specific requirements
- Multiple stakeholder groups with different needs

**Not StRS:**
- Informal user needs → **urd**
- Business-level → **brs** (one level up)
- System-level → **syrs** (one level down)

## Quick create

1. `mcp__archcore__list_documents(types=["strs", "brs", "urd"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What stakeholder classes exist? What BRS does this implement?"
3. Compose content covering all StRS sections — using user's answers and upstream documents for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` — typically `implements` BRS.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `implements` | BRS | Formalizes business requirements |
| Incoming | `implements` | URD | Formalizes user needs |
| Outgoing | `implements` by | SyRS | Next level in cascade |

**Flows:** BRS → **StRS** → SyRS → SRS

Expert — Formalizes system requirements per ISO 29148 by translating StRS into system-level specifications covering boundaries, interfaces, and operational modes. Activates after completing StRS in an ISO 29148 cascade. Not for software-specific requirements — use /archcore:srs.

# SyRS — System Requirements Specification (ISO 29148)

## When to use

- Translating stakeholder requirements (StRS) into system-level specs
- Defining system boundaries, interfaces, and operational modes

**Not SyRS:**
- Stakeholder needs → **strs** (one level up)
- Software-specific → **srs** (one level down)
- Informal product requirements → **prd**

## Quick create

1. `mcp__archcore__list_documents(types=["syrs", "strs"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What system is being specified? What StRS does this implement?"
3. Compose content covering all SyRS sections — using user's answers and upstream documents for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` — typically `implements` StRS.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `implements` | StRS | Formalizes stakeholder requirements |
| Outgoing | `implements` by | SRS | Next level in cascade |

**Flows:** StRS → **SyRS** → SRS

Expert — Documents a recurring task pattern with steps, variations, and known pitfalls. Activates when a task is performed repeatedly — e.g., 'document our release process', 'playbook for X', 'we always do this the same way'. For one-time procedures use /archcore:guide.

# Task-Type — Recurring Task Pattern

## When to use

- A task is performed repeatedly with a standard approach
- Documenting tribal knowledge before it's lost

**Not Task-Type:**
- One-time procedure → **guide**
- Mandatory standard → **rule**
- One-off implementation → **plan**

## Quick create

1. `mcp__archcore__list_documents(types=["task-type", "rule", "guide"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "What recurring task does this cover? What are the key steps?"
3. Compose content covering What, When to Use, Steps, Example, Things to Watch Out For — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `depends_on` | rule | Rule the pattern follows |
| Peer | `related` | guide | Related procedures |

**Flows:** rule → **Task-Type**

Expert — Documents user requirements, personas, and journeys. Activates when defining who the users are and what they need — e.g., 'user research', 'define our personas', 'document user journeys', 'usability requirements'.

# URD — User Requirements Document

## When to use

- Documenting who the users are and what they need
- Mapping user journeys and defining usability requirements

**Not URD:**
- Market analysis → **mrd**
- Business justification → **brd**
- Product scope → **prd**

## Quick create

1. `mcp__archcore__list_documents(types=["urd", "mrd", "brd"])` — check duplicates
2. Use the `AskUserQuestion` tool to ask: "Who are the users? What are their key needs?"
3. Compose content covering User Personas, User Journeys, User Requirements, Usability Requirements, Acceptance Criteria — using user's answers for depth. Pass as `content` to `mcp__archcore__create_document`.
4. Suggest `mcp__archcore__add_relation` based on existing documents.

## Relations

| Direction | Type | Target | When |
|-----------|------|--------|------|
| Outgoing | `implements` by | StRS | Formal stakeholder requirements |
| Peer | `related` | MRD, BRD | Peer source documents |
| Outgoing | `related` | PRD | User context informs product |

**Flows:** MRD+BRD+**URD** → PRD; **URD** → StRS

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
          }
        ]
      }
    ],
    "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
          }
        ]
      }
    ]
  }
}

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.