Enforce Engineering Discipline

Use this skill to replace "find a nearby file, make a minimal patch, finish" with a stricter engineering workflow:

1. Anchor non-trivial work in an OpenSpec change or manual Spec fallback.
2. Establish standards.
3. Understand the real code relationships.
4. Define the change boundary.
5. Make precise edits against Spec/OpenSpec tasks.
6. Validate repeatedly.
7. Keep Spec/OpenSpec and supporting documentation in sync.

Do not claim full understanding until the relevant files, callers, callees, base types, framework constraints, and project standards have been inspected.

Trigger / When-to-use

Use this skill when a task is non-trivial and affects behavior, architecture, data, tests, review outcome, or engineering documentation:

• Implementing a feature, bug fix, refactor, module addition, API change, data change, or workflow change.
• Reviewing a PR, working tree, or named Spec/OpenSpec change.
• Writing tests or validating behavior against requirements and scenarios.
• Creating or updating proposal, design, specs, tasks, work logs, test reports, review reports, or architecture notes.
• Recovering a task when OpenSpec is missing by recommending installation, then using manual Spec fallback if needed.

Do not use this skill for one-line obvious fixes, formatting-only changes, copy edits, or pure Q&A with no implementation or process-file change.

Dispatch

Load the matching reference before doing the work:

• Any non-trivial feature, fix, refactor, review, test, or documentation-impacting task: read references/openspec-governance.md.
• Authoring or updating proposal, design, specs, tasks, or fallback files: read references/spec-standards.md.
• OpenSpec CLI is missing or the project cannot be initialized with OpenSpec: read references/spec-fallback.md.
• Feature work, bug fixes, refactors, or module additions: read references/development-workflow.md.
• Code review, PR review, or working-tree review: read references/review-workflow.md.
• Writing tests or validating behavior: read references/testing-workflow.md.
• Any code change or documentation-affecting task: read references/documentation-sync.md.

For tasks that span multiple categories, load the references in execution order. Example: for a bug fix with tests, read OpenSpec governance first, then development, then testing, and use documentation-sync throughout.

Mandatory Gates

Do not skip these gates on applicable work:

1. Spec gate: confirm OpenSpec is available and initialized, or explicitly enter manual Spec fallback; non-trivial implementation must have an active change with complete required artifacts.
2. Standards gate: identify project conventions, architecture notes, coding standards, and relevant prior decisions before editing.
3. Scope gate: state the Spec/OpenSpec change, task boundary, affected modules, and acceptance criteria.
4. Relationship gate: trace downward dependencies, upward callers, inheritance or interface contracts, and similar local implementations.
5. Layer gate: every new line must have an explicit layer owner: interface, orchestration/business, persistence, computation, integration, or cross-cutting utility.
6. Cleanup gate: remove obsolete fields, methods, imports, compatibility bridges, tombstone comments, and temporary fallback code.
7. Validation gate: run OpenSpec validation when available, or manual Spec fallback checks, plus the smallest meaningful real-path validation first. Repeat fix-and-check loops until no known violations remain, up to three rounds.
8. Documentation gate: keep Spec/OpenSpec artifacts authoritative; update supporting logs, reports, architecture, database, or operations docs when the task changes them.

Blocking Rules

Stop and ask the user when any of these cannot be resolved from the repository:

• OpenSpec CLI is unavailable and the agent has not recommended installation or entered manual Spec fallback.
• The project has no openspec/ directory and the agent has neither initialized OpenSpec nor created the manual Spec fallback structure.
• Non-trivial implementation has no active Spec/OpenSpec change.
• Required Spec/OpenSpec artifacts are missing or blocked.
• The project standards, framework versions, or dependency source/documentation cannot be identified.
• The task scope, boundary, or acceptance criteria are ambiguous enough to change the implementation.
• The impact appears to cross more than five modules.
• Spec/OpenSpec specs, design, tasks, and code reality conflict.
• openspec validate "<name>" --strict fails for the active change, or manual Spec fallback checks fail.
• A self-check still has unresolved violations after three fix-and-check rounds.
• Code and documentation disagree and it is unclear which source is authoritative.
• The project has no usable documentation system and the correct documentation location cannot be determined.

For a new project, recommend installing and initializing OpenSpec first. If that is unavailable, create the manual Spec fallback structure before implementation. If the project also lacks supporting documentation, initialize from assets/project-doc-template/ after the Spec/OpenSpec structure is in place.

Prohibited Shortcuts

• Do not infer framework behavior from memory when the exact version can be inspected.
• Do not bypass Spec/OpenSpec and implement non-trivial work directly.
• Do not implement outside the active Spec/OpenSpec tasks unless the artifacts are updated first.
• Do not mark Spec/OpenSpec tasks complete before the implementation and validation are done.
• Do not modify a subclass without reading its parent class, base class, or interface contract.
• Do not edit a callee without checking important callers.
• Do not invent a new abstraction unless it removes real complexity or matches an established local pattern.
• Do not add compatibility code "just in case."
• Do not do unrelated cleanup or opportunistic refactors.
• Do not approve a review because only pure-function tests pass; verify the real path that matters.
• Do not leave code, Spec/OpenSpec specs, and supporting documentation describing different behavior.

Examples

Example: feature implementation

User: Add team-level image generation quota.
Agent: Use this skill, create/select a Spec/OpenSpec change, write proposal/spec/design/tasks, inspect related quota code, implement only listed tasks, validate scenarios, update task checkboxes and reports.

Example: bug fix

User: Fix storage usage showing 0 for paid members.
Agent: Use this skill, bind to a change, add a requirement/scenario reproducing the value-semantics bug, trace callers and persistence code, fix the bug, run real-path validation, and mark the task complete only after validation.

Example: OpenSpec unavailable

User: Refactor dashboard sync error handling, but OpenSpec is not installed.
Agent: Recommend installing OpenSpec. If unavailable, use `references/spec-fallback.md` and create `openspec/changes/<change>/proposal.md`, `design.md`, `tasks.md`, and `specs/<capability>/spec.md` before editing code.

Example: review

User: Review this branch before merge.
Agent: Use this skill, load the active Spec/OpenSpec artifacts, map Requirement -> Scenario -> Task -> Code path -> Test/check, then report findings by severity.

References / See Also

Bundled references:

• references/openspec-governance.md - OpenSpec-first workflow, CLI usage, validation, and archive rules.
• references/spec-standards.md - Complete proposal/spec/design/tasks authoring standard.
• references/spec-fallback.md - Manual Spec fallback when OpenSpec is unavailable.
• references/development-workflow.md - Implementation workflow and layering discipline.
• references/review-workflow.md - Review workflow and report structure.
• references/testing-workflow.md - Real-path testing and Spec/OpenSpec coverage mapping.
• references/documentation-sync.md - Supporting documentation and report sync rules.
• assets/project-doc-template/ - Optional supporting documentation template.

Related skills:

• $openspec-propose - create proposal, design, specs, and tasks for a new change.
• $openspec-apply-change - implement tasks from an OpenSpec change.
• $openspec-verify-change - verify implementation against specs, design, and tasks.
• $openspec-archive-change - archive completed changes and sync specs.
• $skill-creator - maintain this skill's structure and validation.

External references:

• OpenSpec GitHub: https://github.com/Fission-AI/OpenSpec
• OpenSpec specification format: https://thedocs.io/openspec/concepts/spec-format/
• Public skill repository: https://github.com/KilimiaoSix/agent-skills

Tool and integration notes:

• Primary CLI integration: openspec.
• Optional Git/GitHub integration for publishing changes: git, gh, or the GitHub MCP server when available.
• No mandatory MCP server is required to use this skill; repository files remain the source of truth.