How do I install the Octospec Workflow skill?

Run npx skillmds@latest add mininglamp-oss/octospec-workflow-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Octospec Workflow safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Octospec Workflow?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Octospec Workflow free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Octospec Workflow?

mininglamp-oss (@mininglamp-oss) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Octospec Workflow by mininglamp-oss

Name: Octospec Workflow
Author: mininglamp-oss

Octospec Workflow

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.

File contents

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.

---name: octospec-workflow-2description: 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 workflowThis repository uses the **octospec** engineering standard. When you are asked tomake a non-trivial code change here, run the 4-phase flow instead of editing codedirectly. Rules live in `.octospec/` and are the source of truth for this repo'sconventions.## When to run thisRun the flow for: a new feature, a bug fix, a refactor, an API change, or anychange that touches load-bearing behavior.**Do NOT run the flow** for trivial changes: a typo, a docs-only edit, alint-only fix, a pure config or dependency bump. Just make those directly.## The 4 phasesRun them in order. Each phase maps to a slash command the user can also invokemanually; 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.

Frequently asked questions