new-command-docs

New Command Documentation Checklist

When a new ArcKit command is added, 11 files across the repository must be updated to reflect the new command. This skill provides the complete checklist and exact patterns for each update.

Pre-flight Checks

Before starting, verify these files exist for the new command:

1. Command file: plugins/arckit-claude/commands/{name}.md (required)
2. Template file: .arckit/templates/{name}-template.md AND plugins/arckit-claude/templates/{name}-template.md (required for document-generating commands, skip for utility commands like customize, pages, trello)
3. Guide file: docs/guides/{name}.md AND plugins/arckit-claude/guides/{name}.md (create if missing, see Guide Creation below)

If any required file is missing, create it before proceeding. Templates should be identical between .arckit/templates/ and plugins/arckit-claude/templates/. Guides should be identical between docs/guides/ and plugins/arckit-claude/guides/ (except migration.md and customize.md which have path differences).

Determine the New Count

Read the current count from plugins/arckit-claude/.claude-plugin/plugin.json (the description field contains the current count, e.g., "50 slash commands"). The new count is current + 1.

Update Checklist

Work through these 11 files in order. For exact grep patterns, insertion formats, and line-level detail, see references/file-locations.md.

1. README.md (root)

Update 4 count locations and add a command table row:

• Line ~35: "all {N} commands, autonomous agents" (Claude Code plugin section)
• Line ~41: "all {N} commands, templates, scripts" (Gemini extension section)
• Line ~742: "All {N} ArcKit commands with maturity status" (Command Reference intro)
• Line ~995: "the {N}x{N} command matrix" (Reference packs section)
• Command table: Add a row in the appropriate category section (Foundation, Strategic Context, Requirements & Data, Research & Strategy, Cloud Research, Data Source Discovery, Procurement, Design & Architecture, Implementation, Quality & Governance, UK Government, UK MOD, Documentation & Publishing). Insert alphabetically within the category.

Table row format:

| `/arckit.{name}` | Description of what the command does | [v1](link) [v2](link) | Status |

Status values: Live, Beta, Experimental

2. docs/index.html

Update 8 count locations and add an HTML command card. See references/html-patterns.md for the full HTML template.

Count locations (search for the old number):

• <meta name="description"> tag (~line 6)
• <meta property="og:description"> tag (~line 10)
• Intro paragraph "{N} AI-assisted commands" (~line 459)
• <h2> heading "{N} ArcKit Commands" (~line 670)
• <span id="visible-count"> and adjacent text (~line 729): Showing <span id="visible-count">{N}</span> of {N} commands (TWO numbers on this line)
• Gemini CLI section "all {N} commands" (~line 1423)
• Footer "All {N} commands documented" (~line 1558)

Important: The visible-count span and its adjacent count BOTH need updating. The JavaScript filter counter uses the span, while the static text shows the total.

3. plugins/arckit-claude/.claude-plugin/plugin.json

Update the description field count:

"description": "The Enterprise Architecture Governance Harness - {N} slash commands across strategy, architecture, delivery, and assurance"

4. .claude-plugin/marketplace.json (root)

Update the description field count:

"description": "{N} slash commands across strategy, architecture, delivery, and assurance — including UK Government compliance"

5. plugins/arckit-claude/README.md

Check for any command count references and update. Look for patterns like "{N} commands" or "{N} slash commands".

6. docs/DEPENDENCY-MATRIX.md

This is the most complex update. See references/dependency-matrix-format.md for detailed format.

Steps:

1. Add column: Add | {name} to the header row (line 20) in alphabetical position among existing commands
2. Add cells: Add | | (empty cell) to every existing row at the same column position
3. Fill dependencies: In each existing command's row, fill in M/R/O if the new command consumes that command's output
4. Add row: Add a new row for the command with its dependencies on other commands
5. Update tier groupings: Add the command to the appropriate tier section (Tier 0-12)
6. Update critical paths: Add to relevant workflow paths if applicable
7. Update version section: Bump "Commands Documented" count
8. Add changelog entry: Add a dated entry at the top of the Changelog section

Changelog entry format:

### YYYY-MM-DD - Added {Command Name} Command
- **Added**: `/arckit.{name}` command ({N}th ArcKit command) for {description}
- **Added**: {name} row and column to dependency matrix
- **Updated**: Tier {X} {Tier Name} to include {name} command
- **Dependencies**: {dep1} (M), {dep2} (R), {dep3} (O)
- **Consumed by**: {consumer1} (M/R/O), {consumer2} (M/R/O)

7. docs/WORKFLOW-DIAGRAMS.md

If the new command fits into existing workflow paths, add it to the relevant Mermaid diagrams. See references/dependency-matrix-format.md for Mermaid node format and style colors.

Not all commands need to appear in workflow diagrams. Skip if the command is a utility (customize, pages) or doesn't fit the sequential workflow model.

8. docs/README.md

Add a row to the Documentation Coverage table and update the coverage count:

| `/arckit.{name}` | [{name}.md](guides/{name}.md) | Complete |

Insert alphabetically or in the same position as other files in its category. Update the coverage line:

**Coverage**: {N}/{N} commands documented (100%)

9. CLAUDE.md

Update if needed:

• Command count references: Search for "50 commands" or similar counts
• Multi-instance types list: If the new command supports multi-instance documents (like ADR, DIAG, WARD, DMC, DFD), add it to the multi-instance list in the generate-document-id.sh section
• Agent System table: If the command delegates to an agent, add it to the agent table

10. CHANGELOG.md (root - CLI changelog)

Add an entry under a new or existing version section:

### Added
- `/arckit.{name}` command for {description}

11. plugins/arckit-claude/CHANGELOG.md (plugin changelog)

Add an entry under a new or existing version section:

### Added
- `/arckit.{name}` command for {description}

Guide Creation

If docs/guides/{name}.md doesn't exist, create one based on an existing guide as a template. Good templates to copy from:

• Simple command: docs/guides/plan.md or docs/guides/adr.md
• Research command: docs/guides/research.md or docs/guides/aws-research.md
• Compliance command: docs/guides/principles-compliance.md
• Operations command: docs/guides/devops.md

A guide should contain:

1. Title and description
2. Prerequisites (which artifacts should exist first)
3. Usage examples with sample arguments
4. What the command produces (document type, filename pattern)
5. Tips and best practices

Remember to copy the guide to both docs/guides/ and plugins/arckit-claude/guides/.

Post-Update Verification

After completing all updates, verify no old counts remain:

1. Grep for old count: Search the entire repo for the old number pattern (e.g., "50 commands", "50 slash commands", "50 AI-assisted"). Any remaining matches are locations you missed.
2. Grep for new count: Verify the new count appears in all expected locations.
3. Check the command exists in: README.md table, docs/index.html card, docs/DEPENDENCY-MATRIX.md row/column, docs/README.md coverage table.

# Example verification (replace 49 with old count, 50 with new count)
grep -rn "50 commands\|50 slash commands\|50 AI-assisted\|50/50" README.md docs/index.html plugins/arckit-claude/.claude-plugin/plugin.json .claude-plugin/marketplace.json docs/README.md docs/DEPENDENCY-MATRIX.md

Run Converter

After all documentation updates, regenerate Codex and Gemini formats:

python scripts/converter.py

References

• references/file-locations.md - Exact file paths, grep patterns, and insertion points
• references/html-patterns.md - HTML command card template for docs/index.html
• references/dependency-matrix-format.md - DSM format, changelog format, Mermaid diagram format