Skip to content

Commit 8c9f225

Browse files
MearmanMearman
committed
docs(CHG36): update skills and CLAUDE.md for flag-based CLI
1 parent 34575c4 commit 8c9f225

13 files changed

Lines changed: 438 additions & 71 deletions

File tree

‎.claude/skills/audit-system/SKILL.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
name: audit-system
3+
description: Use when checking whether a live codebase still matches its SysProM document — detects drift, missing nodes, orphaned references, undocumented decisions, and constraint violations
4+
user-invocable: true
5+
allowed-tools: Bash(spm *), Read, Glob, Grep, Agent
6+
---
7+
8+
# Audit System
9+
10+
Compare a live system against its SysProM document to detect drift. Finds nodes that no longer match reality, code that has no provenance, and invariants that are no longer enforced.
11+
12+
## When to Use
13+
14+
- Periodic health check after a period of development
15+
- Before a release, to confirm provenance is current
16+
- After onboarding new contributors who may not have updated the SysProM
17+
- When the SysProM feels stale or incomplete
18+
19+
## Process
20+
21+
```dot
22+
digraph audit {
23+
rankdir=TB;
24+
load [label="1. Load existing\nSysProM document" shape=box];
25+
scan [label="2. Scan codebase\n(parallel subagents)" shape=box];
26+
compare [label="3. Compare document\nvs reality" shape=box];
27+
report [label="4. Present\naudit report" shape=box];
28+
fix [label="5. Fix drift\n(user-approved)" shape=diamond];
29+
validate [label="6. Validate & sync" shape=box];
30+
31+
load -> scan -> compare -> report -> fix;
32+
fix -> validate [label="approved"];
33+
fix -> report [label="more issues"];
34+
}
35+
```
36+
37+
### Step 1: Load existing document
38+
39+
```bash
40+
spm validate
41+
spm stats
42+
```
43+
44+
Review the current state — how many nodes, which types, any existing validation issues.
45+
46+
### Step 2: Scan codebase (parallel subagents)
47+
48+
Dispatch subagents to check each audit dimension. Each subagent reads the SysProM document AND explores the codebase, returning discrepancies.
49+
50+
**Dispatch these in parallel:**
51+
52+
| Subagent | What to check |
53+
|----------|--------------|
54+
| Ghost nodes | Nodes in SysProM that reference files, modules, or concepts that no longer exist |
55+
| Undocumented code | Significant modules, services, or APIs in the codebase with no corresponding SysProM node |
56+
| Decision drift | Decisions recorded in SysProM whose selected option no longer matches reality (e.g. "chose SQLite" but codebase uses Postgres) |
57+
| Invariant enforcement | Invariants claimed in SysProM that are not actually enforced (no lint rule, no test, no type constraint) |
58+
| Relationship accuracy | Relationships that are structurally wrong (A depends_on B but no import exists, A refines B but they are unrelated) |
59+
| Staleness | Nodes with outdated descriptions, names that no longer match, or statuses that should have progressed |
60+
61+
**Subagent prompt template:**
62+
63+
> You are auditing a codebase against its SysProM provenance document.
64+
>
65+
> First, read the SysProM document:
66+
> ```bash
67+
> spm query nodes
68+
> spm query rels
69+
> ```
70+
>
71+
> Then explore the codebase to check for [AUDIT DIMENSION].
72+
>
73+
> For each finding, report:
74+
> - **Issue**: What is wrong
75+
> - **Severity**: critical / warning / info
76+
> - **Node**: Which SysProM node is affected (or "none" for undocumented code)
77+
> - **Evidence**: File path, line, or command output proving the drift
78+
> - **Suggested fix**: What should change in the SysProM document
79+
80+
### Step 3: Compare document vs reality
81+
82+
Collate subagent findings into a structured comparison. Cross-reference to avoid duplicates (e.g. a ghost node and a broken relationship pointing to the same removed module).
83+
84+
### Step 4: Present audit report
85+
86+
Present findings grouped by severity:
87+
88+
```
89+
## Audit Report
90+
91+
### Critical (must fix)
92+
- [ ] EL5 "Redis Cache" — module removed in commit abc123, node still present
93+
- [ ] INV3 "No any types" — 14 uses of `any` found in src/legacy/
94+
95+
### Warnings (should fix)
96+
- [ ] D7 "Use REST" — codebase now also has GraphQL endpoints (undocumented)
97+
- [ ] CP3 → EL8 relationship: EL8 was renamed to EL12
98+
99+
### Info (consider)
100+
- [ ] src/analytics/ has no SysProM coverage (3 modules, ~2000 LOC)
101+
- [ ] CH19 status is "introduced" but all tasks are complete
102+
```
103+
104+
**Wait for user to review before making any changes.**
105+
106+
### Step 5: Fix drift (user-approved)
107+
108+
For each approved fix, use the appropriate CLI command:
109+
110+
| Drift type | Fix |
111+
|-----------|-----|
112+
| Ghost node | `spm remove <id>` or `spm update node <id> --status retired` |
113+
| Undocumented code | `spm add <type> --name "<name>" --description "<desc>"` |
114+
| Decision drift | `spm update node <id> --description "<updated>"` or add new decision |
115+
| Broken invariant | Update invariant description, or add enforcement, or retire |
116+
| Wrong relationship | `spm update remove-rel <from> <type> <to>` then `spm update add-rel <from> <type> <to>` |
117+
| Stale status | `spm update node <id> --status <new-status>` |
118+
119+
### Step 6: Validate and sync
120+
121+
```bash
122+
spm validate
123+
spm json2md .spm.json .spm
124+
```
125+
126+
Confirm zero validation errors after fixes.
127+
128+
## Severity Guide
129+
130+
| Severity | Criteria |
131+
|----------|---------|
132+
| **Critical** | Node references something that does not exist, or invariant is actively violated |
133+
| **Warning** | Document is incomplete or inaccurate but not misleading |
134+
| **Info** | Opportunity to improve coverage or update stale metadata |
135+
136+
## Common Mistakes
137+
138+
- **Fixing without approval** — Always present the full report and wait for the user to approve changes. Some "drift" is intentional.
139+
- **Over-reporting** — Not every file needs a node. Apply the same granularity standards as `discover-system`.
140+
- **Ignoring relationship drift** — Relationships rot faster than nodes. A refactored module may still exist but its dependencies have changed completely.
141+
- **Treating warnings as critical** — Incomplete coverage is normal for living systems. Only flag genuinely misleading provenance as critical.

‎.claude/skills/discover-system/SKILL.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
name: discover-system
3+
description: Use when onboarding an existing codebase or project into SysProM for the first time — bootstraps a new document by exploring the system and populating it with discovered intent, concepts, capabilities, elements, decisions, invariants, and relationships
4+
user-invocable: true
5+
allowed-tools: Bash(spm *), Read, Glob, Grep, Agent
6+
---
7+
8+
# Discover System
9+
10+
Bootstrap a SysProM document from an existing codebase. Explores the system systematically, extracts provenance information, and populates a new document with discovered nodes and relationships.
11+
12+
## When to Use
13+
14+
- Starting SysProM on a project that already has code, docs, and history
15+
- Onboarding to an unfamiliar codebase and want structured understanding
16+
- Creating provenance documentation retrospectively
17+
18+
## Process
19+
20+
```dot
21+
digraph discover {
22+
rankdir=TB;
23+
init [label="1. Init empty document" shape=box];
24+
explore [label="2. Explore system\n(parallel subagents)" shape=box];
25+
review [label="3. Review discoveries\nwith user" shape=diamond];
26+
populate [label="4. Populate nodes\nvia spm CLI" shape=box];
27+
relate [label="5. Add relationships" shape=box];
28+
validate [label="6. Validate & sync" shape=box];
29+
30+
init -> explore -> review;
31+
review -> populate [label="approved"];
32+
review -> explore [label="gaps found"];
33+
populate -> relate -> validate;
34+
}
35+
```
36+
37+
### Step 1: Initialise
38+
39+
Create an empty SysProM document in the project root.
40+
41+
```bash
42+
spm init --path .spm.json --format json --title "<Project Name>" --author "<Author>"
43+
```
44+
45+
### Step 2: Explore (dispatch parallel subagents)
46+
47+
Launch exploration subagents to discover each node type. Each subagent searches the codebase and returns a structured summary — it does NOT write to the document.
48+
49+
**Dispatch these in parallel:**
50+
51+
| Subagent | What to find | Where to look |
52+
|----------|-------------|---------------|
53+
| Intent | Project purpose, goals, mission | README, CLAUDE.md, AGENTS.md, docs/, package.json description, repo description |
54+
| Concepts | Domain models, key abstractions, bounded contexts | src/ type definitions, interfaces, schemas, domain models, glossaries |
55+
| Capabilities | Features, APIs, services, what the system can do | Route handlers, exported functions, CLI commands, public API surface |
56+
| Elements | Modules, packages, key files, infrastructure | Directory structure, package.json workspaces, build config, Dockerfiles |
57+
| Decisions | Architectural choices, technology selections, trade-offs | ADRs (docs/adr/, docs/decisions/), commit messages, config file choices (tsconfig, eslint, framework config), CLAUDE.md conventions |
58+
| Invariants | Rules that must always hold, constraints, policies | Lint rules, type constraints, test assertions, CI checks, validation schemas, CLAUDE.md rules |
59+
60+
**Subagent prompt template:**
61+
62+
> You are exploring a codebase to discover [NODE TYPE] for a SysProM provenance document. Search thoroughly using Glob, Grep, and Read. Return a structured list of discoveries in this format:
63+
>
64+
> For each discovery:
65+
> - **Suggested ID**: [TYPE_PREFIX][N] (e.g. I1, CN3, CP5, EL12, D7, INV4)
66+
> - **Name**: Short descriptive name
67+
> - **Description**: What it is and why it matters
68+
> - **Evidence**: File path and line or source where you found it
69+
> - [Type-specific fields: options/selected/rationale for decisions, conditions for invariants, etc.]
70+
>
71+
> Be thorough but avoid duplicates. Group related items. Aim for the right level of granularity — not every file is an element, not every function is a capability.
72+
73+
### Step 3: Review with user
74+
75+
Present a summary table of all discoveries, grouped by type. Ask the user to:
76+
77+
- Confirm, reject, or modify each discovery
78+
- Identify gaps ("what about the caching layer?")
79+
- Adjust granularity ("these three should be one capability")
80+
- Add context the code doesn't reveal ("we chose X because...")
81+
82+
**Do not proceed to population without user approval.**
83+
84+
### Step 4: Populate nodes
85+
86+
For each approved discovery, create the node via the CLI:
87+
88+
```bash
89+
# Intent
90+
spm add intent --name "<name>" --description "<description>"
91+
92+
# Concepts
93+
spm add concept --name "<name>" --description "<description>"
94+
95+
# Capabilities
96+
spm add capability --name "<name>" --description "<description>"
97+
98+
# Elements
99+
spm add element --name "<name>" --description "<description>"
100+
101+
# Decisions (with options and rationale)
102+
spm add decision --name "<name>" --context "<context>" \
103+
--option "OPT-A:<description>" --option "OPT-B:<description>" \
104+
--selected OPT-A --rationale "<rationale>"
105+
106+
# Invariants
107+
spm add invariant --name "<name>" --description "<description>"
108+
```
109+
110+
### Step 5: Add relationships
111+
112+
Connect nodes with typed relationships based on what the exploration revealed:
113+
114+
```bash
115+
spm update add-rel <from> <type> <to>
116+
```
117+
118+
Common relationship types to look for:
119+
120+
| Pattern | Relationship |
121+
|---------|-------------|
122+
| Intent → Concept | `refines` |
123+
| Concept → Capability | `refines` |
124+
| Capability → Element | `realises` |
125+
| Element → Element | `depends_on` |
126+
| Decision → Element | `affects` |
127+
| Decision → Invariant | `must_preserve` |
128+
| Invariant → Capability | `constrains` |
129+
130+
### Step 6: Validate and sync
131+
132+
```bash
133+
spm validate
134+
spm json2md .spm.json .spm
135+
```
136+
137+
Review any validation warnings and fix before finishing.
138+
139+
## Granularity Guide
140+
141+
| Too coarse | Right level | Too fine |
142+
|-----------|------------|---------|
143+
| "The backend" | "Authentication service" | "validatePassword function" |
144+
| "We use TypeScript" | "Strict TypeScript with no `any`" (invariant) | "tsconfig.json line 4" |
145+
| "The API" | "REST API for user management" | "GET /users/:id endpoint" |
146+
147+
Aim for nodes that a developer would recognise as meaningful architectural units.
148+
149+
## Common Mistakes
150+
151+
- **Populating without review** — Always present discoveries to the user first. Code exploration misses context that humans know.
152+
- **Too many elements** — Not every file is an element. Focus on modules, packages, and architectural boundaries.
153+
- **Missing decisions** — The most valuable nodes are often decisions, which are hardest to discover from code alone. Ask the user about choices that shaped the system.
154+
- **Forgetting relationships** — A graph without edges is just a list. Relationships capture the structure that makes SysProM useful.

‎.claude/skills/init-document/SKILL.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,27 +9,28 @@ user-invocable: true
99

1010
Create a new SysProM document with metadata and directory structure. This sets up a blank document ready for building provenance records.
1111

12-
## Arguments
12+
## Options
1313

14-
- `[path]` — Output path for the document (optional, defaults to `.spm`)
14+
- `--path <value>` — Output path for the document (optional, defaults to current directory)
15+
- `--title <value>` — Document title
16+
- `--scope <value>` — Document scope
17+
- `--format <value>` — Output format: `json`, `md`, or `dir`
1518

1619
## Steps
1720

1821
1. Gather document metadata:
1922
- Document title
2023
- Description
21-
- Author name
22-
- Project or organisation
23-
- Initial version
24+
- Scope
2425

2526
2. Create a new document in Markdown format:
2627
```bash
27-
spm init --path .spm --title "<arg1>" --author "<arg2>" --description "<arg3>"
28+
spm init --path .spm --title "My Project" --scope system
2829
```
2930

3031
3. Or create in JSON format:
3132
```bash
32-
spm init --path .spm.json --format json --title "<arg1>"
33+
spm init --path .spm.json --format json --title "My Project"
3334
```
3435

3536
4. Review the generated structure:

‎.claude/skills/json-to-markdown/SKILL.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,11 @@ user-invocable: true
99

1010
Convert a SysProM document from JSON format (`.spm.json`) to human-readable Markdown format (`.spm/` folder or `.spm.md` single file).
1111

12-
## Arguments
12+
## Options
1313

14-
- `[jsonPath]` — Path to `.spm.json` file
15-
- `[outputPath]` — Output directory or file path (optional)
14+
- `--input <value>` — Path to `.spm.json` file
15+
- `--output <value>` — Output directory or file path
16+
- `--single-file` — Force single-file output format
1617

1718
## Steps
1819

@@ -22,12 +23,12 @@ Convert a SysProM document from JSON format (`.spm.json`) to human-readable Mark
2223

2324
2. Convert to multi-file Markdown (in folder):
2425
```bash
25-
spm json2md <arg1> .spm
26+
spm json2md --input .spm.json --output .spm
2627
```
2728

2829
3. Or convert to single-file Markdown:
2930
```bash
30-
spm json2md <arg1> .spm.md --single-file
31+
spm json2md --input .spm.json --output .spm.md --single-file
3132
```
3233

3334
## Output Structure

‎.claude/skills/markdown-to-json/SKILL.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ user-invocable: true
99

1010
Convert a SysProM document from Markdown format (`.spm/` folder or `.spm.md` file) to machine-parseable JSON format (`.spm.json`).
1111

12-
## Arguments
12+
## Options
1313

14-
- `[markdownPath]` — Path to `.spm/` folder or `.spm.md` file
15-
- `[outputPath]` — Output JSON file path (optional, defaults to `.spm.json`)
14+
- `--input <value>` — Path to `.spm/` folder or `.spm.md` file
15+
- `--output <value>` — Output JSON file path
1616

1717
## Steps
1818

@@ -22,12 +22,12 @@ Convert a SysProM document from Markdown format (`.spm/` folder or `.spm.md` fil
2222

2323
2. Convert multi-file Markdown to JSON:
2424
```bash
25-
spm md2json .spm .spm.json
25+
spm md2json --input .spm --output .spm.json
2626
```
2727

2828
3. Or convert single-file Markdown to JSON:
2929
```bash
30-
spm md2json .spm.md .spm.json
30+
spm md2json --input .spm.md --output .spm.json
3131
```
3232

3333
## Output Structure

0 commit comments

Comments
 (0)