1 1 export const DOCUMENT_CONTRACT
= `# The System document contract 3 3 Use .system bundles only. 5 -Every authored document lives at .system/<type-plural>/<ID>-<slug>/index.md. 7 -ID shape: <PREFIX>-<TYPE>-<8 chars from A-Z0-9_->. 11 -Frontmatter refs store IDs only. 12 -Config schemaVersion is 0. 4 +Authored documents live at .system/<type-plural>/<ID>-<slug>/index.md with lowercase slugs. 14 5 Type directories: research, specs, phases, plans, issues. 6 +ID shape: <PREFIX>-<TYPE>-<8 chars from A-Z0-9_->. 7 +Frontmatter refs store IDs only; config schemaVersion is 0. 16 9 Required frontmatter: 17 10 - research: id, type: research, title 20 13 - plan: id,
type: plan, title, spec,
status: draft
|approved, optional
depends_on: plan ID[]
21 14 - issue: id,
type: issue, title,
specs: string[]
23 -Research references no System stage type.
24 -Specs may reference research.
25 -Operate only the explicitly invoked
/system lifecycle stage.
26 -Never auto
-chain stages or create bundles for another stage.
27 -You may recommend another stage; wait for explicit human invocation.
16 +Research links to no stage; specs may reference research; issues have no status field.
17 +Plan depends_on targets earlier plans for the same spec.
28 18 Phases are project
-wide operating epochs related to MISSION, not spec decomposition or work breakdown.
29 19 Phase labels contain
1-12 ASCII letters, digits, dots, underscores, or hyphens.
30 -Plans reference one spec and may depend on earlier plans for the same spec.
31 -Issues may reference zero or more specs and have no status field.
32 -Approved plans are immutable outside an explicitly approved
/system init bundle migration; otherwise create a
new plan bundle.
20 +Config currentPhase selects the operating phase; changing it requires explicit human confirmation.
21 +Operate only the invoked
/system stage; never auto
-chain or create bundles for another stage.
22 +Recommend the next stage, then wait for explicit human invocation.
23 +Approved plans are immutable outside an approved
/system init bundle migration; otherwise create a
new plan bundle.
33 24 Mutating existing core files or files
in phase and spec bundles requires one
-shot human approval.
34 -The optional config currentPhase ID selects the project
-wide operating phase.
35 -Changing currentPhase requires explicit human confirmation.
36 25 Keep prose terse, minimal, and essential.
37 26 After creating or materially editing a System
document, end
with:
43 32 export const MARKDOWN_CONTRACT
= `# The System Markdown contract 45 34 Use readable Markdown. 46 -Prefer visual explanations and diagrams when they clarify structure or relationships. 47 -Use GFM tables/task lists only when they clarify. 48 -Use Mermaid, TeX, raw HTML, and assets only when prose is worse. 49 -After choosing GFM, TeX, or Mermaid, load its matching the-system-* skill. 35 +Model structure, sequence, state, entities, and decisions visually by default. 36 +Use prose for intent, judgment, and constraints. 37 +When content is a structure, flow, state machine, relation, comparison, or branch, select a format first, then load its matching the-system-* skill. 38 +Mermaid models systems, GFM tables enumerate comparisons, TeX states formal relations, raw HTML mockups show visual or interactive surfaces. 39 +Terse governs prose, not models; a diagram that replaces a paragraph is the terse form. 50 40 Keep local Markdown links relative so /system view and /system book can resolve them. 51 41 System documents contain no real code snippets; use terse pseudocode only when essential. 54 -const BOARD_CONTRACT
= `# The System board contract 44 +export const BOARD_CONTRACT
= `# The System board contract 56 46 Board state lives only in .system/board.json at schema version 0. 57 47 Specs and plans use todo|done; issues use open|done. 58 48 A spec may be done without plans, but cannot be done while any linked plan is todo. 59 49 Issues never change spec state. 60 50 Assessment proposes board changes for human review; it never applies them. 51 +Exec applies verified states directly through system_board_update, recorded with source agent and a terse evidence note. 52 +Claim a state only from verification you ran and read; the human overrides any entry in /system board. 63 55 const EXEC_CONTRACT
= `# The System exec contract 68 60 The current phase is already project context;
do not request or attach it
as an exec input.
69 61 Load the vertical
-slices skill before implementation.
70 62 Execute
in thin vertical slices
of behavior required by the referenced documents.
63 +Referenced documents define required outcome, not implementation order.
64 +Re
-sequence layered plan content into vertical slices and implement all
of it.
65 +Do not pause for human approval between slices.
71 66 Each slice delivers one complete, observable behavior through the system
's user-facing or public interface, crossing every layer that behavior requires. 72 67 Do not batch work horizontally by architectural layer or component.
73 68 Integrate, test, and freshly verify each slice before starting the next; leave the repository working after every slice.
74 69 Use tests for nontrivial behavior.
75 70 Debug
root cause before fixing bugs.
76 71 Before claiming implementation complete, run fresh verification and read the full result.
77 -After fresh verification, call system_board_propose exactly once
with evidence
-backed state changes for referenced bundles; use an empty items list when no changes are justified.
78 -Board proposals require human review and never apply automatically.
72 +After fresh verification, call system_board_update exactly once
with the states your work proves for referenced bundles; use an empty items list when no change is justified.
73 +Each update carries a terse note naming the evidence; a rejected update means the claimed state violates a board invariant.
79 74 Final log includes refs, changed areas, verification, and a copyable View block.
80 75 Commit messages tell the
document-linked story, not file
/test inventory.
97 92 If relevant specs exist, ask whether later specs should reference the research; research bundles never link to stages.
`, 98 93 spec: `Create or amend terse specs
as context requires.
99 94 Capture high
-level intent, scope, behavior, constraints, and acceptance criteria.
100 -Use mockups and diagrams when they clarify visual elements, UI, layout, interactions, or relationships.
95 +Every spec models its behavior visually
with at least one diagram, mockup, or state model; a prose
-only spec is incomplete.
96 +Use mockups for visual elements, UI, layout, and interactions, and diagrams for structure, flow, states, and relationships.
101 97 Persist accepted visual assets and their required local dependencies inside the spec bundle.
102 98 Link or embed them from index.md, and encode accepted feedback
as behavior and constraints.
103 99 Do not prescribe implementation.
122 118 When transitioning, create or amend the phase first, then update config currentPhase only after explicit human confirmation.
123 119 Do not mutate MISSION.
`, 124 120 plan: `Create or amend terse implementation plans for specs
as context requires.
125 -Plan at
module, interface,
package, or
class level.
121 +Decompose by observable behavior, not by architectural layer, and order behaviors by delivery value.
122 +Name the modules, interfaces, packages, or classes each behavior touches, without a layer
-by
-layer build order.
123 +Model the
module and interface structure,
or the behavior sequence,
as a diagram.
124 +Show dependencies between plans and between behaviors visually.
126 125 Avoid function and line detail except critical paths.
127 126 Do not include real code snippets.
128 127 Use terse pseudocode only when necessary.
130 129 Status: approved requires human approval and makes each plan immutable.
`, 131 130 issue: `Create or amend terse issues
as context requires.
132 131 Record symptom, impact, reproduction or evidence, and related specs.
132 +Use a sequence diagram for reproduction when the failure crosses components.
133 133 Use
specs: []
while the violated contract is unknown.
134 134 Amend or create specs only when issues expose spec gaps.
`, 135 - exec: EXEC_CONTRACT, 135 + exec: `${BOARD_CONTRACT}
138 139 const NEEDS_MARKDOWN = new Set([ 148 149 export function systemPromptFor(
149 150 subcommand
: string,
150 151 instructions
: string,
152 + boardState
?: string,
152 154 const stage
= STAGE_PROMPTS[subcommand];
153 155 if (
!stage)
throw new Error(
`Unknown /system subcommand: ${subcommand}`);
156 158 ...(NEEDS_MARKDOWN.
has(subcommand)
? [MARKDOWN_CONTRACT]
: []),
157 159 `# /system ${subcommand}`,
161 + ...(boardState?.
trim()
? [boardState.
trim()]
: []),
159 162 instructions.
trim()
160 163 ? `# Human instructions\n\n${instructions.trim()}` 161 164 : "# Human instructions\n\nNo instructions were supplied. Infer intent with focused questions or selection before writing.",