sirius-skills

sirius-skills is a generic-first skill collection for spec-driven development, planning, implementation support, and repository workflows.

Installing skills

Use the repository Makefile to register the managed skill set:

make install

To remove the same managed skill set later:

make uninstall

The intended direction is:

• keep core workflow skills reusable across personal and company projects
• express project-specific conventions through local configuration
• isolate domain or company logic in project-local extensions instead of hardcoding it into the base skills

Generic-first workflow

The managed repo-first skill set is grouped into:

• repo utilities: skills/bootstrap/, skills/commit/, skills/create-pr/, skills/simplify/
• artifact maintenance: skills/audit-artifacts/, skills/trace-artifacts/, skills/report-artifacts/, skills/repair-artifacts/, skills/archive-artifacts/
• planning layer: skills/guide-scope/, skills/guide-planning/, skills/propose/, skills/add-subfeature/, skills/migrate-subfeatures/, skills/assess/, skills/discover/, skills/design/, skills/ui-flow/, skills/breakdown/, skills/review-planning/
• execution layer: skills/slice/, skills/guide-execution/, skills/execute-all-slices/, skills/brief/, skills/blueprint/, skills/review-execution/, skills/close-slice/

If a project has no extra configuration, these skills should still work with generic conventions.

For the operational guide to using the skills together, see SKILLS_METHODOLOGY.md. For developer-facing examples of how to prompt the skills, see PROMPT_GUIDE.md.

Planning layer

For repositories that use repo-first planning, the recommended short-name planning skills are:

• skills/guide-scope/
• skills/guide-planning/
• skills/propose/
• skills/add-subfeature/
• skills/migrate-subfeatures/
• skills/assess/
• skills/discover/
• skills/design/
• skills/ui-flow/
• skills/breakdown/
• skills/review-planning/

These skills sit before the execution-slice skills:

• planning layer: guide-scope, guide-planning, propose, add-subfeature, migrate-subfeatures, assess, discover, design, ui-flow, breakdown, review-planning
• execution layer: slice, guide-execution, execute-all-slices, brief, blueprint, review-execution, close-slice

Recommended boundary:

• keep goals, design, stories, decomposition, and increment plans in repo documents
• keep executable slices and dependency tracking in the repository planning artifacts
• stop planning at review-planning until a human explicitly approves the planning artifacts
• commit approved planning artifacts before bootstrapping execution with slice
• bootstrap one execution slice per executable slice
• use guide-scope as the optional scope-aware entrypoint when multi-scope routing or explicit scope choice matters
• let guide-planning own feature-planning readiness and routing inside the planning layer
• let guide-execution own slice readiness and state transitions within the execution layer
• let execute-all-slices orchestrate one reviewed and committed feature or subfeature backlog without absorbing the owning execution steps

Feature-local planning defaults to docs/features/<feature-slug>/ unless the active planning scope's .skills/planning.json defines a different planning_dir. Planning-layer helpers first look for the nearest .skills/planning.json in ancestor directories, then fall back to the repository root when inside a Git worktree.

Proposal staging defaults to docs/proposals/<proposal-slug>/ unless the active planning scope's .skills/planning.json defines a different proposal_dir.

Preferred repo workflow:

1. In multi-scope repositories, guide-scope can resolve the active scope, stop on ambiguity, and hand off to guide-planning, guide-execution, or bootstrap without changing their ownership rules. In single-scope repositories it remains optional.
2. guide-planning resolves the feature planning folder, validates planning readiness, and routes to the right planning skill.
3. If the request is still speculative and should not become a canonical feature yet, propose creates a proposal folder under docs/proposals/<proposal-slug>/.
4. If the request adds or reshapes a durable child capability under an existing feature, add-subfeature creates a subfeature folder under docs/features/<feature>/subfeatures/<subfeature-id>/.
5. assess inspects the parent feature and writes subfeature-scoped impact-analysis.md before subfeature-local design starts.
6. discover creates problem framing and initial story candidates.
7. design turns that into architecture, interfaces, and risks.
8. ui-flow adds optional UX or screen-flow artifacts.
9. breakdown turns repo stories into directly executable work items and groups those slices into small demonstrable increments.
10. review-planning reviews planning artifacts and slice definitions, then stops for explicit human approval.
11. After approval, commit the planning artifacts so the reviewed plan is durable before execution begins.
12. slice validates approved, committed execution-ready input, bootstraps a slice-scoped execution slice, and hands off to guide-execution.
13. guide-execution routes slice-scoped execution through brief to capture slice intent and acceptance, then through blueprint to produce the final execution artifact. When .skills/execution.json enables auto_start_implementation, that handoff continues directly into implementation after the blueprint is marked ready.
14. execute-all-slices is the optional batch entrypoint when a reviewed and committed feature or subfeature backlog should be worked one planned slice at a time. It resumes or bootstraps one mapped slice, then stops at the next owning execution step or commit checkpoint.
15. review-execution checks implementation and validation outcomes against the slice-scoped execution artifacts before closure.
16. close-slice closes completed execution slices and records durable closure metadata.
17. After closure, keep the subfeature planning folder and closed slice artifacts in place. If a repository wants later cleanup or archival, handle that through maintenance tooling such as archive-artifacts, not a dedicated subfeature-finalization skill.

For repositories that still contain legacy changes/ packets from the old workflow, migrate-subfeatures can scan and convert those legacy planning folders into the current durable subfeatures/ layout before normal planning work continues.

In the repo-native flow, guide-planning owns feature-planning readiness and routing, breakdown owns repo-story decomposition, review-planning owns planning readiness review, slice owns execution bootstrap from approved committed planning artifacts, brief owns the slice-scoped brief.md, blueprint owns the final slice-scoped execution plan and validation checklist, and review-execution owns the final implementation-versus-brief review before closure.

Execution follows the same pattern: guide-execution owns routing, readiness, and registry state, while brief, blueprint, review-execution, and close-slice own slice-scoped artifacts and closure metadata. With auto_start_implementation, guide-execution can promote a slice from blueprint_ready to execution_ready as the signal to begin coding immediately.

execute-all-slices sits above that single-slice flow as an optional orchestrator. It resolves one reviewed and committed feature or subfeature backlog, resumes or bootstraps one mapped execution slice at a time, and hands the next step back to guide-execution or commit. It does not replace slice, guide-execution, review-execution, close-slice, or commit.

By default, new execution slices are created under slices/ unless .skills/execution.json overrides the location.

When UML diagrams are useful, use PlantUML:

• design should produce feature-scoped system-design diagrams in system-design.md
• blueprint should produce slice-scoped detailed-design diagrams in blueprint.md

By default, design embeds PlantUML directly in system-design.md. If .skills/planning.json sets "design_diagram_mode": "linked_svg", design should instead write .puml and .svg files under <feature_path>/figures/ and link the SVGs from system-design.md. In that mode, keep diagrams on an explicit white background by setting skinparam backgroundColor white in PlantUML and ensuring the rendered SVG includes a white canvas rect.

Execution slice source of truth

The guide-execution workflow now keeps three complementary artifacts in sync:

• <slice_dir>/README.md for a human-readable registry
• <slice_dir>/registry.json for machine-readable registry/state
• <slice_path>/.slice-meta.json for per-slice lifecycle metadata such as created_at, updated_at, closed_at, and explicit relation metadata

The machine-readable metadata can also store explicit cross-slice relations such as supersedes, invalidates, narrows, and replaces_partially, with reciprocal backlinks and optional soft selectors for story titles, requirement IDs, or freeform selectors.

Closed slices are retained non-destructively. sirius-skills does not merge or delete the original brief.md/blueprint.md artifacts when a slice closes; instead it records closure durably in the slice registry and metadata.

Per-slice closure is non-destructive. sirius-skills keeps closed slices and durable subfeature planning folders in place by default; any later cleanup or archival should happen through explicit maintenance tooling instead of an automatic feature-finalization step.

To keep relation metadata healthy over time, skills/guide-execution/scripts/manage_execution.py also provides audit-relations, which checks for missing targets and missing reciprocal links.

Example prompts

Examples of repo-native prompts that fit the current workflow:

• "Audit workflow artifacts across proposals, features, subfeatures, and slices."
• "Trace workflow lineage across proposals, features, subfeatures, planned slices, and execution slices."
• "Report workflow state across proposals, features, subfeatures, and slices."
• "Preview and repair workflow registry drift across proposals, features, subfeatures, and slices."
• "Report archive candidates and archive one closed execution slice safely."
• "Use guide-planning to decide the next step for planning-workflow."
• "Create a proposal for a new review automation feature, but keep it out of canonical planning for now."
• "Add a durable subfeature replace-legacy-flow under checkout and frame its discovery docs."
• "Assess the impact of subfeature replace-legacy-flow under checkout."
• "Design the subfeature at docs/features/checkout/subfeatures/replace-legacy-flow/."
• "Break down docs/features/checkout/subfeatures/replace-legacy-flow/ into execution-ready slices."
• "Review planning for the replace-legacy-flow subfeature before slice bootstrap."
• "Use execute-all-slices for docs/features/checkout/subfeatures/replace-legacy-flow/ and continue until a blocker or per-slice commit checkpoint stops the run."
• "Finalize subfeature replace-legacy-flow under checkout after its planned slices are closed."
• "Scan the repo for legacy changes/ packets that still need migration."
• "Dry-run migration of old changes/ packets under checkout into durable subfeatures."

For a broader developer prompt cookbook, including prompt-first design and reverse-engineered current-state design, see PROMPT_GUIDE.md.

Optional project configuration

Use skills/bootstrap/ when you want an agent to bootstrap the repo's supported .skills/planning.json, .skills/execution.json, and .skills/conventions.json files. The skill supports a generic default mode, a Jira-oriented jira mode, and an ask mode that makes the agent stop and ask the user which preset to apply before writing config.

Projects can add .skills/planning.json in the repository root to configure planning-layer layout.

Example:

{
  "planning_dir": "planning/features",
  "proposal_dir": "planning/proposals",
  "design_diagram_mode": "embedded"
}

Projects can add .skills/conventions.json in the repository root to describe their local conventions.

Projects can add .skills/execution.json in the repository root to configure execution-slice layout for guide-execution and slice bootstrap.

Example:

{
  "slice_dir": "slices",
  "preferred_workflow": "TDD",
  "auto_start_implementation": true
}

Example:

{
  "issue_sliceer": "jira",
  "id_pattern": "^[A-Z][A-Z0-9]*-[0-9]+$",
  "branch_extract_pattern": "^([A-Z][A-Z0-9]*-[0-9]+)-(.+)$",
  "commit_format": "{ID}: {summary}",
  "pr_title_format": "{ID}: {summary}",
  "issue_url_template": "https://jira.example.com/browse/{ID}"
}

Current Phase 1 usage:

• skills/guide-scope/SKILL.md documents the optional scope-aware entrypoint for routing multi-scope work into planning, execution, or bootstrap
• planning-layer skills resolve .skills/planning.json from the nearest scope, then fall back to the repository root when inside a Git worktree; planning_dir still defaults to docs/features/<feature-slug>/
• skills/propose/scripts/manage_proposals.py reads the active scope's .skills/planning.json field proposal_dir when present and otherwise defaults to docs/proposals/<proposal-slug>/
• skills/guide-planning/scripts/manage_planning.py reads the active scope's .skills/planning.json for planning_dir and maintains planning readiness metadata under <feature_path>/.planning-meta.json
• skills/design/SKILL.md reads .skills/planning.json field design_diagram_mode; embedded keeps fenced PlantUML in system-design.md, while linked_svg writes .puml and .svg files under <feature_path>/figures/, links the SVGs from system-design.md, and keeps those SVGs on an explicit white canvas
• skills/breakdown/scripts/scaffold_breakdown.py uses .skills/planning.json field planning_dir during scaffolding when the file is present
• skills/slice/scripts/bootstrap_slice.py resolves the nearest execution scope, reuses inherited scoped execution config when present, and only initializes .skills/execution.json locally when no execution config exists in the scope chain
• skills/guide-execution/scripts/manage_execution.py resolves .skills/execution.json, .skills/conventions.json, and slice_dir from the active execution scope so nested scopes keep local slice registries and folders
• when auto_start_implementation is true, skills/guide-execution/scripts/manage_execution.py set-status <slice> blueprint_ready auto-advances the slice into execution_ready
• skills/guide-execution/scripts/manage_execution.py uses branch_extract_pattern during add when the file is present
• skills/commit/SKILL.md documents how commit_format can override the generic default
• skills/create-pr/SKILL.md documents how pr_title_format, branch_extract_pattern, and id_pattern can define stricter PR conventions

If the file is absent, the generic defaults remain in effect.

Project-local extensions

Use .skills/plugins/ as the project-local area for company or domain add-ons.

Important: this is currently a convention, not an automatically loaded plugin system. Nothing in sirius-skills scans or executes .skills/plugins/ by itself today.

Current usage model:

• put project-local helper configs or scripts in .skills/plugins/
• have a specific skill or script read them explicitly
• document that behavior in the relevant skill

Today, the project-local files that are actually consumed automatically are .skills/planning.json, .skills/conventions.json, and .skills/execution.json.

Examples:

• .skills/plugins/jira-validator.json
• .skills/plugins/jira-backlog-analyzer.py
• .skills/plugins/iso14229-reviewer.py

Example of how to use the convention today:

• a future create-pr implementation could read .skills/plugins/jira-validator.json
• a future review-pr or review-bsp-uds-code implementation could import .skills/plugins/iso14229-reviewer.py
• a future planning skill could read .skills/plugins/jira-backlog-analyzer.py

Core skills should only rely on these extensions when a project explicitly opts in. This keeps sirius-skills reusable while still allowing company overlays.