specflo 0.2.0__py3-none-any.whl

specflo/_repo_skills/spec/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: spec
+description: Use at a specflo project's spec phase, when turning a validated brainstorm into a structured, testable spec before any plan or code. Triggers include "write the spec", "let's spec this out", or `specflo status` showing the spec phase. Do NOT use for trivial fixes or before a brainstorm has been validated.
+---
+
+# Spec (specflo)
+
+## Overview
+
+Turn a validated `brainstorm.md` into a **validated `spec.md`** for the active
+specflo project: an objective, numbered **testable `REQ-NN` requirements** (each
+with a pass/fail acceptance criterion, traced to the `D-NN` decision it derives
+from), explicit in/out boundaries, and open questions — then hand off toward the
+plan phase. The `specflo` CLI does the artifact I/O; you carry the synthesis,
+judgment, and discipline.
+
+## When to use / When NOT
+
+**Use** at the spec phase (the second of `brainstorm → spec → plan → execute`),
+once the brainstorm is validated. The spec is a **synthesis of the brainstorm,
+not a new interview** — read `brainstorm.md` and write requirements; do not
+re-litigate settled decisions.
+
+**Do NOT use** for trivial fixes, or before a brainstorm exists and passes
+`specflo validate brainstorm`. If the brainstorm is incomplete, finish it first.
+
+## HARD-GATE
+
+Do NOT write code, scaffold anything, or take any implementation action until the
+spec is validated (`specflo validate spec` passes) and the user has explicitly
+approved. The discipline here is the **rigor of the artifact** — testable
+requirements with pass/fail acceptance — not merely "don't code yet".
+
+## Process
+
+1. **Preflight.** Confirm an active project at the spec phase (`specflo status`).
+   Run `specflo spec start` to create or locate `spec.md` (the command prints its
+   path — never build the path yourself). Read the project's `brainstorm.md`:
+   its Decisions (`D-NN`), Research, Current understanding, and Out of scope.
+2. **Draft requirements — translate decisions, reframe vague → testable.** For
+   each thing the system must do, write a falsifiable requirement. Two moves:
+   - **Decision → behavior.** Brainstorm decisions are often *architecture or
+     tech-stack* choices ("build on SDK X", "UI in framework Y"), not behaviors —
+     and have no inherent pass/fail. Make each testable by spec'ing the
+     **behaviors it exists to enable**, and expect one decision to **fan out into
+     several requirements** (e.g. "build on the SDK" → separate auth, discovery,
+     and version-compatibility requirements, each `--from` that decision).
+   - **Reframe fuzzy wants:** `"make it fast"` →
+     `"the landscape scan returns within 5s on a warm cache"`, then ask "are these
+     the right targets?".
+   A good requirement is **✓** "API responds in < 200ms at p95"; a bad one is
+   **✗** "the system should be fast".
+3. **Give every requirement a pass/fail acceptance criterion.** No subjective
+   criteria — write how a verifier confirms it. The check may be **behavioral**
+   (observe the running system) or **structural** (a source- or dependency-scan)
+   — both are valid as long as the verdict is mechanical. An architectural
+   constraint ("all server I/O goes through the SDK; no hand-rolled client") is
+   legitimately verified structurally; don't contort it into a fake runtime test.
+   Trace it to the decision it comes from with `--from D-NN` where applicable.
+4. **Capture inline.** The moment a requirement is settled, record it:
+   `specflo requirement add --text "…" --acceptance "…" [--from D-NN]`
+   (add `--supersedes REQ-NN` when it replaces an earlier one). Don't batch —
+   capture as they happen. Keep the prose sections (Objective, Boundaries In/Out,
+   Open questions, Canonical refs) current by editing `spec.md` directly.
+5. **Hold the scope boundary.** Fill **Boundaries** — In scope and Out of scope —
+   carrying the brainstorm's Out of scope / Deferred forward. Both lists must be
+   non-empty.
+6. **No stale specifics.** The spec is behavioral and durable: no file paths or
+   code snippets that churn. One exception — a small prototype snippet that
+   encodes a decision more precisely than prose can (a schema or type shape).
+7. **Self-review.** Re-read the spec with fresh eyes: placeholder scan; internal
+   consistency (do requirements contradict?); two-way ambiguity (pick one reading
+   and make it explicit); scope (one plan, or should this decompose?).
+8. **Gate + validate.** Ask the user an explicit "ready?". On yes, run
+   `specflo validate spec`; fix any reported gaps inline and re-run until it
+   passes.
+9. **Hand off — pause at the phase boundary.** Surface the end of the phase as one
+   clear beat, and **do not auto-advance**: the spec is complete and validated, the
+   **checkpoint is saved** (the project's `checkpoint.md`; resume any time with
+   `specflo checkpoint`), so this is a **safe place to clear context**. The plan
+   phase is next (it synthesizes from `spec.md` and cites `REQ-NN` — no
+   re-interview). Then **wait** — `specflo advance` is the user's to call; don't
+   change the phase yourself or start the plan.
+
+## Anti-sycophancy
+
+Take a position on every requirement and state what evidence would change it.
+Avoid filler validation: "That's a great requirement," "That could work," "There
+are many ways to think about this." Challenge the strongest version of the
+user's intent, not a strawman. If a requirement isn't testable, say so and
+reframe it.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The brainstorm is enough." | The brainstorm captures *decisions*, not *testable requirements*. The spec adds acceptance criteria a verifier can check. |
+| "A tech-stack decision isn't a requirement." | It is — spec the *behaviors* it exists to enable. One decision usually fans out into several testable requirements, each `--from` it. |
+| "I'll write the acceptance after I code it." | That's a test report, not a specification. Decide pass/fail *before* building. |
+| "This requirement is obviously testable." | If you can't state the pass/fail check in one line, it isn't. Write the line. |
+| "I'll re-ask the user to be safe." | Re-interviewing is not synthesis. Read `brainstorm.md`; only ask about genuine gaps. |
+| "Boundaries are obvious." | Unwritten scope is where plans balloon. Write In and Out explicitly. |
+
+## Red flags (stop and correct)
+
+- A requirement has no pass/fail acceptance criterion.
+- You wrote a requirement into chat prose instead of `specflo requirement add`.
+- You re-interviewed the user on something the brainstorm already decided.
+- You put file paths or churn-prone code snippets into `spec.md`.
+- You moved toward the plan without an explicit user "ready?" and a passing
+  `specflo validate spec`.
+- You built or scaffolded something during the spec phase.
+
+## Verification checklist
+
+- [ ] `specflo spec start` was run; `spec.md` exists for the active project.
+- [ ] Every requirement is in the Requirements section via `specflo requirement add`.
+- [ ] Every requirement has a pass/fail **Acceptance** criterion.
+- [ ] **Boundaries** — In scope and Out of scope — are both filled in.
+- [ ] **Open questions** is present (may say "none").
+- [ ] `specflo validate spec` passes.
+- [ ] The user explicitly approved readiness before handoff.
+- [ ] At hand-off, the checkpoint-saved phase-end beat was surfaced and `specflo advance` was left to the user.
+- [ ] No code or scaffolding was produced.

specflo/brainstorm.py

@@ -0,0 +1,179 @@
+"""The brainstorm artifact and its operations.
+
+Each project gets a single ``brainstorm.md`` next to ``project.md``. The CLI owns
+the structured, stateful parts of this file — scaffolding, the append-only
+Decisions section (stable ``D-NN`` IDs, supersede-as-event), and read-only
+linting. The brainstorm skill writes the prose sections (Current understanding,
+Out of scope, Open questions, Canonical refs) directly.
+"""
+
+from __future__ import annotations
+
+import datetime
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import SpecfloConfig
+from .errors import SpecfloError
+from . import markdown
+from .projects import load_project, project_dir
+
+BRAINSTORM_FILENAME = "brainstorm.md"
+
+_DECISION_ID_RE = re.compile(r"^### (D-\d+) —", re.MULTILINE)
+
+_TEMPLATE = """\
+---
+project: {slug}
+phase: brainstorm
+status: draft
+created: {today}
+updated: {today}
+---
+
+# Brainstorm: {name}
+
+## Current understanding
+<!-- rewritten as it converges; the synthesis the spec phase reads -->
+
+## Research
+<!-- findings + surprises from the research subagent (optional); links go to Canonical refs -->
+
+## Decisions
+<!-- append-only; managed by `specflo decision add`. Stable IDs D-NN. -->
+
+## Out of scope / Deferred
+<!-- required, must be non-empty before validate passes -->
+
+## Open questions
+<!-- required section (may say "none") -->
+
+## Canonical refs
+<!-- full paths the brainstorm leaned on -->
+"""
+
+
+@dataclass
+class Decision:
+    id: str
+    text: str
+    rationale: str
+    supersedes: str | None
+    status: str
+
+
+def brainstorm_path(root: Path, cfg: SpecfloConfig, slug: str) -> Path:
+    return project_dir(root, cfg, slug) / BRAINSTORM_FILENAME
+
+
+def start_brainstorm(
+    root: Path, cfg: SpecfloConfig, slug: str, today: str | None = None
+) -> tuple[Path, bool]:
+    """Create the brainstorm artifact, or locate an existing one.
+
+    Returns ``(path, created)``; ``created`` is False if the file already existed
+    (resume-friendly — never clobbers).
+    """
+    project = load_project(root, cfg, slug)  # raises SpecfloError if missing
+    path = brainstorm_path(root, cfg, slug)
+    if path.exists():
+        return path, False
+    today = today or datetime.date.today().isoformat()
+    path.write_text(
+        _TEMPLATE.format(slug=project.slug, name=project.name, today=today)
+    )
+    return path, True
+
+
+def add_decision(
+    root: Path,
+    cfg: SpecfloConfig,
+    slug: str,
+    text: str,
+    rationale: str | None = None,
+    supersedes: str | None = None,
+    today: str | None = None,
+) -> Decision:
+    """Append a decision to the Decisions section and return it.
+
+    Assigns the next ``D-NN`` id. If ``supersedes`` is given, the named decision
+    is marked superseded (kept in place) and linked from the new entry.
+    """
+    path = brainstorm_path(root, cfg, slug)
+    if not path.is_file():
+        raise SpecfloError("No brainstorm yet. Run `specflo brainstorm start` first.")
+    doc = path.read_text()
+    if "## Decisions" not in doc:
+        raise SpecfloError("Malformed brainstorm.md: no '## Decisions' section.")
+
+    if supersedes is not None and not re.search(
+        rf"^### {re.escape(supersedes)} —", doc, re.MULTILINE
+    ):
+        raise SpecfloError(f"No decision {supersedes} to supersede.")
+
+    new_id = markdown.next_id(doc, "D-")
+    rationale_text = rationale if rationale else "—"
+
+    if supersedes is not None:
+        doc = markdown.mark_superseded(doc, supersedes, new_id)
+
+    entry_lines = [f"### {new_id} — {text}", f"- Rationale: {rationale_text}"]
+    if supersedes is not None:
+        entry_lines.append(f"- Supersedes: {supersedes}")
+    entry_lines.append("- Status: active")
+    entry = "\n".join(entry_lines) + "\n"
+
+    doc = markdown.append_to_section(doc, "## Decisions", entry)
+    doc = markdown.bump_updated(doc, today)
+    path.write_text(doc)
+    return Decision(
+        id=new_id,
+        text=text,
+        rationale=rationale_text,
+        supersedes=supersedes,
+        status="active",
+    )
+
+
+def complete_brainstorm(
+    root: Path, cfg: SpecfloConfig, slug: str, today: str | None = None
+) -> None:
+    """Mark the brainstorm complete (``status: draft → complete``); bump ``updated``.
+
+    Called when leaving the brainstorm phase (by `specflo advance`). Raises
+    ``SpecfloError`` if the artifact is missing.
+    """
+    path = brainstorm_path(root, cfg, slug)
+    if not path.is_file():
+        raise SpecfloError("No brainstorm yet. Run `specflo brainstorm start` first.")
+    doc = path.read_text()
+    # Frontmatter `status:` only — the leading-`-` decision `- Status:` lines and
+    # the count=1 (frontmatter comes first) keep this from touching entries.
+    doc = re.sub(r"(?m)^status:.*$", "status: complete", doc, count=1)
+    doc = markdown.bump_updated(doc, today)
+    path.write_text(doc)
+
+
+def validate_brainstorm(root: Path, cfg: SpecfloConfig, slug: str) -> list[str]:
+    """Return a list of lint issues (empty == ready). Read-only."""
+    path = brainstorm_path(root, cfg, slug)
+    if not path.is_file():
+        return ["brainstorm.md not found — run `specflo brainstorm start`."]
+    doc = path.read_text()
+    body = markdown.strip_comments(doc)
+    issues = markdown.placeholder_issues(body)
+
+    if not _DECISION_ID_RE.search(doc):
+        issues.append("no decisions captured (need at least one).")
+
+    out_of_scope = markdown.section_body(doc, "## Out of scope / Deferred")
+    if out_of_scope is None:
+        issues.append("missing 'Out of scope / Deferred' section.")
+    elif not markdown.strip_comments(out_of_scope).strip():
+        issues.append("'Out of scope / Deferred' section is empty.")
+
+    if markdown.section_body(doc, "## Open questions") is None:
+        issues.append("missing 'Open questions' section.")
+
+    return issues

specflo/checkpoint.py

@@ -0,0 +1,183 @@
+"""The `checkpoint` resume prompt — derived, agent-facing "resume here" state.
+
+After every state-mutating command specflo rewrites a per-project
+``checkpoint.md``: a short, derived prompt telling a freshly-cleared agent which
+phase we're in, which files to read first, and the concrete next action. It is
+fully derived from project state (phase + existing artifacts + the workflow's
+next step), so it can be written automatically and is always current.
+
+Mirrors ``guide.py``: pure derivation (``build_checkpoint``) + a renderer
+(``render_checkpoint``) + a thin writer (``write_checkpoint``).
+"""
+
+from __future__ import annotations
+
+import datetime
+from pathlib import Path
+
+from . import plan as plan_module, validators, workflow
+from .brainstorm import BRAINSTORM_FILENAME
+from .config import SpecfloConfig, display_path
+from .projects import (
+    COMPLETE_STATUS,
+    PROJECT_FILENAME,
+    SHELVED_STATUS,
+    Project,
+    project_dir,
+)
+from .spec import SPEC_FILENAME
+
+CHECKPOINT_FILENAME = "checkpoint.md"
+
+# Phase artifacts in pipeline order. ``checkpoint.md`` lists only the ones that
+# actually exist, so there are no dangling references and the list grows on its
+# own as later artifacts (plan.md, ...) land.
+_ARTIFACT_ORDER: list[str] = [BRAINSTORM_FILENAME, SPEC_FILENAME, "plan.md"]
+
+
+def checkpoint_path(root: Path, cfg: SpecfloConfig, slug: str) -> Path:
+    return project_dir(root, cfg, slug) / CHECKPOINT_FILENAME
+
+
+def build_checkpoint(
+    root: Path,
+    project: Project,
+    cfg: SpecfloConfig | None = None,
+    today: str | None = None,
+) -> dict:
+    """Derive the resume-prompt payload for ``project`` from current state.
+
+    Read-only: inspects which artifacts exist on disk but mutates nothing.
+
+    ``cfg`` is threaded from the write path so brainstorm/spec/plan can derive
+    honest doneness — running the phase's real validator inline (REQ-01/03).
+    Without it (a bare ``build_checkpoint`` call), the static work hint stands.
+    """
+    directory = project.path
+    read_first = [display_path(directory / PROJECT_FILENAME, root, posix=True)]
+    for filename in _ARTIFACT_ORDER:
+        if (directory / filename).is_file():
+            read_first.append(display_path(directory / filename, root, posix=True))
+    shelved = project.status == SHELVED_STATUS
+    plan_file = directory / plan_module.PLAN_FILENAME
+    prog = None
+    plan_doc = None
+    milestone = None
+    boundary = None
+    # A shelved project's do_next ignores progress, so skip the plan-file read.
+    if not shelved and project.phase in ("plan", "execute") and plan_file.is_file():
+        plan_doc = plan_file.read_text()
+        prog = plan_module.progress_from_doc(plan_doc)
+        # The current milestone (None on a milestone-free or all-complete plan),
+        # named in the resume block at plan/execute so a resumed agent knows which
+        # slice the plan is on (REQ-15). Dormant without milestones (REQ-04).
+        milestone = plan_module.current_milestone_from_doc(plan_doc)
+        # The soft milestone-boundary verify beat (None off a boundary): the
+        # just-completed milestone's Exit checklist to verify before proceeding
+        # (REQ-14). Surfaced in the resume block; never a hard stop.
+        boundary = plan_module.milestone_boundary_from_doc(plan_doc)
+    if shelved:
+        # Paused: don't direct to the phase's work step — resume (or start new),
+        # while the recorded phase below is preserved so resume returns to it.
+        do_next = workflow.next_step(project.phase, shelved=True)
+    elif project.phase == "execute":
+        do_next = workflow.next_step(
+            "execute", progress=prog, complete=project.status == COMPLETE_STATUS
+        )
+        # Stuck on a superseded dependency: surface the same targeted rewire
+        # remediation as `task show`/`status`, replacing the generic hint.
+        if project.status != COMPLETE_STATUS and plan_doc is not None:
+            stuck = plan_module.stuck_next_step_from_doc(plan_doc)
+            if stuck:
+                do_next = stuck
+    else:
+        # Derived doneness (REQ-01/03): run the phase's real validator inline
+        # (no memoization) — a passing validator flips the hint to offer-advance,
+        # a failing or missing artifact reads as work-in-progress. cfg is threaded
+        # from the write path; without it the static work hint stands.
+        validates = False
+        if cfg is not None:
+            validator = validators.VALIDATORS.get(project.phase)
+            if validator is not None:
+                validates = not validator(root, cfg, project.slug)
+        do_next = workflow.next_step(project.phase, validates=validates)
+        # A plan that doesn't yet validate still names its next task; once it
+        # validates the offer-advance hint stands alone.
+        if project.phase == "plan" and not validates and prog is not None:
+            if prog["next_actionable"]:
+                do_next += "  (next task: " + ", ".join(prog["next_actionable"]) + ")"
+            elif prog["all_done"]:
+                do_next += "  (all tasks done)"
+    return {
+        "project": project.slug,
+        "phase": project.phase,
+        "status": project.status,
+        "shelved_reason": project.shelved_reason,
+        "generated": today or datetime.date.today().isoformat(),
+        "read_first": read_first,
+        "do_next": do_next,
+        "milestone": milestone,
+        "boundary": boundary,
+        "path": display_path(directory / CHECKPOINT_FILENAME, root, posix=True),
+    }
+
+
+def render_checkpoint(payload: dict) -> str:
+    """Render the payload to the markdown written to ``checkpoint.md``."""
+    shelved = payload.get("status") == SHELVED_STATUS
+    subtitle = f"_phase: {payload['phase']}"
+    if shelved:
+        subtitle += " (shelved)"
+    subtitle += f" | generated {payload['generated']}_"
+    lines = [
+        f"# Checkpoint - {payload['project']}",
+        subtitle,
+        "",
+    ]
+    if shelved and payload.get("shelved_reason"):
+        lines += [f"**Shelved:** {payload['shelved_reason']}", ""]
+    lines += [
+        "## Read first",
+        *(f"- {path}" for path in payload["read_first"]),
+        "",
+        "## Do next",
+        payload["do_next"],
+    ]
+    # Name the current milestone in the resume block so a resumed agent knows
+    # which slice the plan is on (REQ-15); absent on a milestone-free plan.
+    milestone = payload.get("milestone")
+    if milestone:
+        lines.append(
+            f"Current milestone: {milestone['id']} {milestone['title']} "
+            f"— {milestone['done']}/{milestone['total']} done."
+        )
+    # The soft milestone-boundary verify beat: the just-completed milestone's Exit
+    # checklist for a user-gated proceed (REQ-14). Absent off a boundary.
+    boundary = payload.get("boundary")
+    if boundary:
+        lines += ["", "## Milestone boundary", *plan_module.boundary_beat_lines(boundary)]
+    lines += [
+        "",
+        "## Resume",
+        "- `specflo status`     - confirm phase/step",
+        "- `specflo checkpoint` - reprint this prompt",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def write_checkpoint(
+    root: Path,
+    project: Project,
+    cfg: SpecfloConfig | None = None,
+    today: str | None = None,
+) -> Path:
+    """Render the checkpoint for ``project`` and write ``checkpoint.md``.
+
+    ``cfg`` is forwarded to :func:`build_checkpoint` so the written checkpoint
+    reflects derived doneness for brainstorm/spec/plan (REQ-01).
+    """
+    payload = build_checkpoint(root, project, cfg=cfg, today=today)
+    path = project.path / CHECKPOINT_FILENAME
+    path.write_text(render_checkpoint(payload))
+    return path