Imported from londey/syskit (templates/syskit/AGENTS.md). Install upstream with npx skills add londey/syskit --skill syskit. Copyright stays with the author.

syskit — AI Assistant Instructions

This project uses syskit for specification-driven development.

New to syskit? Run /syskit-guide for an interactive walkthrough.

Document Locations

All persistent engineering documents live under doc/:

• doc/requirements/ — What the system must do
• doc/interfaces/ — Contracts between components and with external systems
• doc/design/ — How the system accomplishes requirements
• doc/verification/ — How requirements are verified
• doc/reports/ — Technical reports and investigation findings (working documents)
• ARCHITECTURE.md — Auto-generated architecture overview with block diagram (project root)

Working documents live under .syskit/:

• .syskit/analysis/ — Impact analysis results (ephemeral)
• .syskit/tasks/ — Implementation task plans (ephemeral)
• .syskit/manifest.md — SHA256 hashes of all doc files

Reference material for subagents:

• .syskit/ref/ — Detailed format specs (requirement quality, cross-references, Spec-ref)
• .syskit/prompts/ — Subagent prompt templates

Document Types

• Requirements (req_NNN_<name>.md) — WHAT the system must do. Use condition/response format.
• Interfaces (int_NNN_<name>.md) — Contracts between components and external systems.
• Design Units (unit_NNN_<name>.md) — HOW the system works. Links to requirements and interfaces.
• Verification (ver_NNN_<name>.md) — HOW requirements are verified. Links to requirements and design units.

Key Principle

Reference, don't reproduce. Don't restate information that is defined elsewhere — reference the source.

• Internal documents: Reference by ID (REQ-NNN, INT-NNN, UNIT-NNN, VER-NNN). Each fact should have exactly one authoritative location in doc/.
• External standards: Reference by name, version/year, and section or figure number (e.g., "ISO 26262-6:2018 §8.4.4", "RFC 9293 §3.1", "PNG 1.2 §4.1.3"). Don't paraphrase normative text — cite the section that defines it.
• Scope: Applies to specification documents and code (comments, docstrings). Working files in .syskit/ are exempt.

For detailed format and style guidance, see .syskit/ref/document-formats.md.

Workflows

Important: Always invoke syskit scripts using workspace-relative paths (e.g., .syskit/scripts/manifest.sh). Never expand these to absolute paths.

Investigating First (Optional)

If a topic needs investigation before proposing changes, use /syskit-technical-report to explore the codebase and document findings. The report can then serve as context when running /syskit-impact.

Before Making Changes

Always run impact analysis first:

1. Read the manifest to get the current document inventory
2. Delegate document reading and analysis to a subagent — subagent writes results to disk and returns only a brief summary
3. Validate the subagent's summary counts against the manifest
4. Check manifest for any documents modified since last analysis

Proposing Changes

1. Ensure doc/ has no uncommitted changes (clean git status required)
2. Create analysis folder: .syskit/analysis/<date>_<change_name>/
3. Delegate change drafting to subagent(s) — subagents read impact.md from disk, edit doc/ files directly, and write a lightweight summary to proposed_changes.md
4. Generate snapshot.md by running: .syskit/scripts/manifest-snapshot.sh <analysis-folder>
5. User reviews changes via git diff doc/ and approves, refines, or rejects

Refining Changes (Iterative)

After proposing, the user may want to iterate on the proposed changes before approving:

1. Run /syskit-refine --feedback "<what needs to change>" to fix issues in the proposal
2. Review updated changes via git diff doc/
3. Repeat with additional /syskit-refine runs as needed (each in a new conversation)
4. Run /syskit-approve when satisfied (or approve inline during propose/refine)

Use refine to fix issues in proposed changes — wrong decisions, missing coverage, incorrect interfaces, etc.

Approving Changes

Approval can happen inline (during /syskit-propose or /syskit-refine) or in a separate session:

1. Run /syskit-approve to review and approve pending changes from any previous session
2. The approve command reads the analysis folder, shows the current diff, and updates proposed_changes.md status
3. This enables overnight reviews — propose in one session, review at your leisure, approve in another

Planning Implementation

After spec changes are approved:

1. Delegate scope extraction and task creation to a subagent — subagent reads proposed_changes.md and git diff, writes plan.md and task files to disk
2. Generate snapshot.md by running: .syskit/scripts/manifest-snapshot.sh <task-folder>
3. Tasks should be small enough to implement and verify independently

Implementing

1. Delegate implementation to a subagent — subagent reads the task file and all referenced files, makes changes, verifies, returns a summary
2. After each task, run post-implementation scripts to verify consistency
3. Run .syskit/scripts/trace-sync.sh to validate forward references
4. Run .syskit/scripts/impl-check.sh to verify Spec-ref consistency (missing / orphan / untracked)
5. Run .syskit/scripts/ver-check.sh to verify Ver-ref consistency (missing / orphan / untracked)
6. After doc changes, run .syskit/scripts/arch-update.sh to refresh ARCHITECTURE.md
7. After doc changes, run .syskit/scripts/manifest.sh to update the manifest
8. Run .syskit/scripts/template-check.sh to verify documents conform to current templates

Context Budget Management

The workflow commands use subagents to keep document content out of the main context window. Follow these rules to prevent context exhaustion:

1. Subagents write to disk, return only summaries — A subagent's final message becomes a tool result in the main context. Keep return messages under 1KB. Write detailed output to files in .syskit/analysis/ or .syskit/tasks/.

2. Subagents read large files from disk — Never paste file content larger than 2KB into a subagent prompt. Instead, give the subagent the file path and let it read the file itself.

3. Chunk large change sets — When more than 8 documents are affected, use multiple subagents each handling a subset. Assemble results with .syskit/scripts/assemble-chunks.sh.

4. Validate via summaries, not content — Verify subagent work by checking counts and file lists in the returned summary. Do not read large output files into the main context for review.

5. Edit doc files directly — Subagents edit doc/ files in place. The user reviews via git diff. This eliminates the largest context consumer (full proposed content for every affected file).

6. One command per conversation — Each syskit command persists all state to disk. Start a fresh conversation for each command to avoid context accumulation.

Template Conformance

Documents may drift from their templates when templates are updated between installer runs. The template-check script verifies that all required sections are present:

.syskit/scripts/template-check.sh                  # check all documents
.syskit/scripts/template-check.sh --type req        # check requirements only
.syskit/scripts/template-check.sh doc/design/unit_001_core.md  # check one file

Exit code 0 means all documents conform; exit code 1 means missing sections were found. When editing an existing document, run the check on that file first — if the template has gained new sections since the document was written, add them before making other changes.

Freshness Checking

Analysis and task files include SHA256 snapshots of referenced documents.

When loading previous analysis or tasks, run the check script:

.syskit/scripts/manifest-check.sh <path-to-snapshot.md>

Exit code 0 means all documents are fresh; exit code 1 means some have changed.

File Numbering

When creating new documents:

• Find highest existing number in that category
• Use next number with 3-digit padding: 001, 002, etc.
• Use _ separator, lowercase, no spaces in names

Helper scripts:

.syskit/scripts/new-req.sh <name>
.syskit/scripts/new-req.sh --parent REQ-004 <name>
.syskit/scripts/new-int.sh <name>
.syskit/scripts/new-int.sh --parent INT-005 <name>
.syskit/scripts/new-unit.sh <name>
.syskit/scripts/new-unit.sh --parent UNIT-002 <name>
.syskit/scripts/new-ver.sh <name>
.syskit/scripts/new-ver.sh --parent VER-001 <name>

Cross-References

Use REQ-NNN, INT-NNN, UNIT-NNN, VER-NNN identifiers (or REQ-NNN.NN, INT-NNN.NN, UNIT-NNN.NN, VER-NNN.NN for children) when referencing between documents.

References are unidirectional — each document only declares forward references, never back-references:

• INT → references nothing
• REQ → may reference INT
• UNIT → may reference REQ and INT
• VER → may reference REQ, UNIT, and INT

Use .syskit/scripts/trace-query.sh <ID> for reverse lookups (e.g., "what implements REQ-001?").

For detailed rules, see .syskit/ref/cross-references.md.

For Spec-ref implementation traceability, see .syskit/ref/spec-ref.md.

For Ver-ref test traceability, see .syskit/ref/ver-ref.md.

Architecture Overview

After adding or modifying design units, refresh the architecture overview:

.syskit/scripts/arch-update.sh

This updates the Mermaid block diagram and unit summary table in ARCHITECTURE.md between guard tags.