name

octospec-workflow

description

Use when implementing a feature, fixing a bug, or making any non-trivial code change in this repository. Drives the octospec 4-phase engineering flow (Plan, Implement, Verify, Finish) so the change follows this repo's rules in .octospec/ and ships a PR with a linked spec. Triggers on requests like "add ...", "implement ...", "fix ...", "refactor ...", "change the ... API", 写功能, 修 bug, 加接口, 改逻辑. Skip for trivial edits (typo, docs, lint, pure config) — those do not need the flow.

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.
If a learning is worth reusing, stage it in .octospec/learnings/pending/ (promotion into rules/ is a separate reviewed PR — do not auto-edit rules).
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.

octospec workflow

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.

If a learning is worth reusing, stage it in .octospec/learnings/pending/ (promotion into rules/ is a separate reviewed PR — do not auto-edit rules).

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.