speccoder_runtime/format/openspec/
texts.rs

1//! OpenSpec's paths, rules and words: intent is all of `openspec/`;
2//! planning writes active changes only; archiving is the person's.
3
4use std::path::Path;
5
6use crate::format::{Assess, Messages, Planning, Rules, Wording};
7
8/// OpenSpec's intent and planning rules.
9pub static RULES: Rules = Rules {
10    intent: &["openspec", "openspec/**"],
11    intent_reason: "it is OpenSpec intent (openspec/): the spec is not edited during implementation",
12    authoring_path: is_authoring_path,
13    command,
14    // OpenSpec's CLI asks no questions of a sandboxed child and phones home
15    // unless told not to.
16    env: &[
17        ("OPENSPEC_TELEMETRY", "0"),
18        ("DO_NOT_TRACK", "1"),
19        ("OPENSPEC_NO_UPDATE_CHECK", "1"),
20    ],
21    found_env: crate::format::no_found_env,
22    authoring_refusal,
23};
24
25/// What a hosted planning skill writes: active changes, never the archive.
26fn is_authoring_path(p: &str) -> bool {
27    p.starts_with("openspec/changes/") && !p.starts_with("openspec/changes/archive/")
28}
29
30fn authoring_refusal(p: &str) -> String {
31    format!(
32        "a planning skill writes OpenSpec changes (openspec/changes/, not its archive); `{p}` is not one"
33    )
34}
35
36/// The OpenSpec subcommand of `argv`: `openspec …`, `npx openspec …` or
37/// `npx @fission-ai/openspec[@version] …`.
38fn subcommand(argv: &[String]) -> Option<&[String]> {
39    let program = argv.first()?;
40    let name = program.rsplit('/').next().unwrap_or(program);
41    if name == "openspec" {
42        return Some(&argv[1..]);
43    }
44    if name == "npx" {
45        let rest: Vec<&String> = argv[1..].iter().filter(|a| !a.starts_with('-')).collect();
46        let package = rest.first()?;
47        let bare = package
48            .strip_prefix("@fission-ai/")
49            .unwrap_or(package)
50            .split('@')
51            .next()
52            .unwrap_or_default();
53        if bare == "openspec" {
54            let at = argv.iter().position(|a| a == *package)?;
55            return Some(&argv[at + 1..]);
56        }
57    }
58    None
59}
60
61/// OpenSpec's CLI (contracts/policy.md): reading is free, creating a change
62/// is planning, everything that rewrites intent or the installation is
63/// refused — archiving above all, which is the person's.
64fn command(argv: &[String], authoring: bool) -> Option<Result<(), String>> {
65    let sub = subcommand(argv)?;
66    let first = sub.first().map_or("", String::as_str);
67    match first {
68        "" | "--version" | "-V" | "--help" | "-h" | "list" | "show" | "status"
69        | "instructions" | "validate" | "schemas" | "templates" | "context" | "view" => {
70            Some(Ok(()))
71        }
72        "new" if authoring => Some(Ok(())),
73        "new" => Some(Err(
74            "creating an OpenSpec change is planning, not implementation".to_owned(),
75        )),
76        "archive" => Some(Err(
77            "archiving rewrites the main specs and is the person's: they run `speccoder spec archive`"
78                .to_owned(),
79        )),
80        "sync" | "init" | "update" | "config" | "store" | "schema" => Some(Err(format!(
81            "`openspec {first}` changes OpenSpec's intent or installation; speccoder never runs it"
82        ))),
83        _ => None,
84    }
85}
86
87/// What the model is told about OpenSpec.
88pub static WORDING: Wording = Wording {
89    product: "OpenSpec",
90    name: "OpenSpec",
91    unit: "change",
92    intent_paths: "openspec/",
93    intent_code: "`openspec/`",
94    documents: "proposal, design, spec deltas and tasks.md",
95    authoring: "write OpenSpec changes (openspec/changes/, never its archive) and run OpenSpec's read commands and `openspec new change`",
96    authoring_tool: "an OpenSpec command",
97    story: "Spec deltas",
98    constitution: "Project context",
99    plan: "Change proposal and design",
100    plan_short: "Proposal and design",
101    examples: "the scenarios of the change's spec deltas that this task concerns (name the capability, requirement and scenario each test covers in a comment above it)",
102    convergence_task: "A task in a Convergence group",
103    files: ["spec deltas", "proposal and design", "tasks.md"],
104    assess: Assess {
105        rules: "the project context",
106        targets: "ADDED or MODIFIED requirement and each of its scenarios, design decision and project context constraint",
107        must: "a SHALL or MUST of the deltas",
108        sources: "proposal, design, deltas and tasks",
109        critical: "a SHALL or MUST not met, or missing/contradicts on a MODIFIED requirement",
110        refs: "greeting: Farewell / Farewell with name, design: argv parsing",
111    },
112};
113
114/// What a person is told about an OpenSpec project.
115pub static MESSAGES: Messages = Messages {
116    tasks_file: "tasks.md",
117    make_tasks: "create it with `speccoder spec propose`",
118    not_a_project,
119    no_project: "not an OpenSpec project (no openspec/ found)",
120    no_project_in_worktree: "the worktree has no OpenSpec project",
121    not_in_git: "the OpenSpec project is not inside a git repository",
122    no_skills: "no skills installed (OpenSpec installs them with `openspec init`, under .claude/skills/)",
123    checklists,
124    unit: "change",
125    no_current: "OpenSpec has no current change: name one with --change",
126    current_shared: "",
127    make_project: ("openspec init", "make it an OpenSpec project"),
128};
129
130fn not_a_project(path: &Path) -> String {
131    format!(
132        "no OpenSpec project (openspec/) at or above {}; run `openspec init` first",
133        path.display()
134    )
135}
136
137fn checklists(open: &str) -> String {
138    format!("unfinished checklists: {open}")
139}
140
141/// OpenSpec's planning skills.
142pub static PLANNING: Planning = Planning {
143    prefix: "openspec-",
144    core: &[],
145    refused,
146    // `propose` creates a change (and writes its proposal, deltas and
147    // tasks in one pass): the first step of a project without one.
148    creates: &["propose"],
149    current_env: None,
150    toward_tasks,
151    revises: None,
152    checks: None,
153};
154
155fn toward_tasks(_has_plan: bool) -> &'static [&'static str] {
156    &["propose"]
157}
158
159/// Skills speccoder does not host, and what to use instead.
160fn refused(name: &str) -> Option<String> {
161    match name {
162        "openspec-apply-change" => {
163            Some("speccoder is the apply step, with evidence: use `speccoder run`".to_owned())
164        }
165        "openspec-sync-specs" | "openspec-archive-change" => Some(
166            "merging a change into the main specs is the person's: use `speccoder spec archive`"
167                .to_owned(),
168        ),
169        _ => None,
170    }
171}
172
173#[cfg(test)]
174mod tests {
175    use super::*;
176
177    fn argv(s: &str) -> Vec<String> {
178        s.split_whitespace().map(str::to_owned).collect()
179    }
180
181    #[test]
182    fn openspec_commands_by_subcommand() {
183        for (line, implementing, planning) in [
184            ("openspec list --json", Some(true), Some(true)),
185            (
186                "openspec validate x --strict --json",
187                Some(true),
188                Some(true),
189            ),
190            (
191                "npx @fission-ai/openspec@1.14.3 show x",
192                Some(true),
193                Some(true),
194            ),
195            ("npx -y openspec status", Some(true), Some(true)),
196            ("openspec new change add-x", Some(false), Some(true)),
197            ("openspec archive x --yes", Some(false), Some(false)),
198            ("/usr/local/bin/openspec sync", Some(false), Some(false)),
199            ("openspec init", Some(false), Some(false)),
200            ("openspec frobnicate", None, None),
201            ("cargo test", None, None),
202        ] {
203            let a = argv(line);
204            assert_eq!(
205                command(&a, false).map(|r| r.is_ok()),
206                implementing,
207                "{line}"
208            );
209            assert_eq!(command(&a, true).map(|r| r.is_ok()), planning, "{line}");
210        }
211        let why = command(&argv("openspec archive x"), false)
212            .unwrap()
213            .unwrap_err();
214        assert!(why.contains("speccoder spec archive"), "{why}");
215        assert!(is_authoring_path("openspec/changes/add-x/proposal.md"));
216        assert!(!is_authoring_path(
217            "openspec/changes/archive/2026-x/tasks.md"
218        ));
219        assert!(!is_authoring_path("openspec/specs/greeting/spec.md"));
220    }
221}
speccoder_runtime/format/openspec/texts.rs

speccoder_runtime/format/openspec/
texts.rs
