Octospec Workflow

octospec workflow

This repository uses the octospec engineering standard. When you are asked to make a non-trivial code change here, run the 4-phase flow instead of editing code directly. Rules live in .octospec/ and are the source of truth for this repo's conventions.

When to run this

Run the flow for: a new feature, a bug fix, a refactor, an API change, or any change that touches load-bearing behavior.

Do NOT run the flow for trivial changes: a typo, a docs-only edit, a lint-only fix, a pure config or dependency bump. Just make those directly.

The 4 phases

Run them in order. Each phase maps to a slash command the user can also invoke manually; as a skill you perform the same steps.

1. Plan

• Choose a short kebab-case <slug>.
• Read .octospec/tasks/_brief.template.md.
• Inspect the relevant existing code, then write .octospec/tasks/<slug>/brief.md with: Goal, Load-bearing list (use the same tags as .octospec/rules/_index.yaml inject_when.touches where they apply), Out of scope, Acceptance.
• Show the brief and get confirmation before writing code.

2. Implement

• Resolve applicable rules: read .octospec/rules/_index.yaml and .octospec/_global/ (if synced). A rule applies when its inject_when.paths glob matches a file you will touch, OR its inject_when.touches tag is in the brief's load-bearing list. A repo-tier rule overrides a global one with the same id.
• Read the full text of each matching rule and follow it. Prioritize load_bearing: true rules.
• Record what you used in .octospec/tasks/<slug>/context.yaml.
• Write the code. Do not commit yet.

3. Verify

• Review the diff against each injected rule (trace load-bearing paths, not just the happy path).
• Confirm the diff meets the brief's Acceptance and did not touch anything in Out of scope.
• Run this repo's gates (lint / type-check / tests; see CLAUDE.md / AGENTS.md).
• Self-fix what you can.

4. Finish

• Run the final gate once more.
• Write .octospec/journal/shared/<slug>.md (what was done + any learning). Start it with OKF frontmatter (type: Journal + title/description/tags/ timestamp) and add a dated entry to .octospec/log.md.
• Promote any reusable learning in this same PR: edit the relevant .octospec/rules/<rule>.md in place (or add a new rule + _index.yaml entry) — the PR review is the gate. The helper .octospec/scripts/octospec-update-spec.sh gives you the raw material (--kind=rule → a draft in learnings/pending/<slug>-rule-draft.md + a promotion block on stdout; --kind=task → a per-actor journal entry). It never auto-writes rules/, so you copy the draft into rules/<id>.md and update _index.yaml here, in this PR, then drop the scratch draft — never defer it to a separate PR or a later move. Only use .octospec/learnings/pending/ for unresolved learnings that still need human design before becoming a rule; finished learnings must not be stranded waiting on a phantom separate PR.
• Open a PR. Fill the PR template's Linked Spec (→ the brief) and the COMPREHENSION three questions to substance, for load-bearing / architectural / P0 changes.

Notes

• This skill orchestrates the flow automatically. The user can still drive any single phase manually with /octospec-plan, /octospec-go, /octospec-check, /octospec-finish.
• The flow is guidance, not a hard gate; the repo's PR/CI checks are the enforcement layer.