principled

Validate that a pull request follows principled conventions: references a plan or proposal, has correct labels, includes required sections in the description, and links to relevant documents. Use in CI or before merging to enforce PR quality.

Generate a structured pull request description from a DDD plan task. Reads the plan, task manifest, and implementation branch to produce a PR body with references to the originating proposal, plan, ADRs, and related tasks. Use when opening a PR for plan-driven work.

Process open GitHub issues through the principled pipeline. Lists untriaged issues, normalizes their metadata, ingests them into the documentation pipeline, and reports a summary. Operates as the batch entry point — delegates to /ingest-issue for each individual issue.

Implementation orchestration strategy for the Principled framework. Consult when working with DDD plan execution, git worktrees for task isolation, task manifests, or the decompose-spawn-validate-merge lifecycle. Covers worktree management, sub-agent patterns, task state machines, and manifest schema.

Top-level orchestrator for DDD plan execution. Decomposes a plan into tasks, iterates through phases respecting dependencies, spawns worktree-isolated agents, validates implementations, and merges results. Runs inline to coordinate multiple sub-agent spawns. Use for automated end-to-end plan execution.

Audit ADR coverage across modules. Identifies modules with no architectural governance, orphaned ADRs referencing removed modules, and stale architecture docs. Classifies findings by severity.

Detect violations of architectural decisions in the codebase. Checks module dependency direction rules, identifies boundary violations, and reports drift between documented decisions and actual code.

Generate a map linking modules to their governing ADRs and architecture documents. Scans all modules via CLAUDE.md discovery, cross-references ADRs and architecture docs, and classifies governance coverage as Full, Partial, or None.

Answer natural-language questions about the architecture by cross-referencing ADRs, architecture docs, proposals, and the codebase. Designed for onboarding and architecture exploration.

Architecture governance strategy for the Principled framework. Consult when working with architecture maps, drift detection, coverage audits, architecture document sync, or module boundary enforcement. Covers dependency direction rules, governance mapping conventions, and the heuristic analysis approach.

Update architecture documents to reflect the current codebase state. Compares documented modules, types, and components against actual code and proposes updates for human review. Never auto-modifies.

Run the full CI pipeline locally, mirroring the checks in .github/workflows/ci.yml. Use to verify everything passes before pushing.

Propagate canonical templates and scripts to all consuming skills, then verify zero drift. Use after updating any canonical template or script to keep all copies in sync.

Smoke-test all enforcement hooks by feeding known good and bad inputs and verifying exit codes. Tests the ADR immutability guard, the proposal lifecycle guard, the manifest integrity advisory, the PR reference advisory, the review checklist advisory, and the release readiness advisory.

Generate changelog entries from the principled documentation pipeline. Maps commits to proposals, plans, and ADRs since the last release tag, groups by category, and renders Markdown changelog sections.

Draft a human-reviewable release plan summarizing all changes since the last tag, grouped by module and category. Includes outstanding items and suggested release steps.

Verify that all pipeline documents referenced by merged changes are in terminal status. Checks proposals, plans, and ADRs to ensure release readiness before tagging.

Release strategy for the Principled framework. Consult when working with changelogs, release readiness checks, version bumps, release plans, or tag operations. Covers changelog format conventions, semver bump heuristics, pipeline reference resolution, and the release lifecycle.

Tag and finalize a release. Validates the tag, verifies release readiness, generates changelog and release notes, creates the git tag, and optionally creates a GitHub release.

Coordinate version bumps across module manifests. Detects modules via CLAUDE.md, determines bump type from pipeline signals, and applies version changes to manifest files.

Generate the complete documentation structure for a new module. Use when creating a new app or lib module, or when asked to scaffold, initialize, or set up module documentation. Module type must be specified explicitly.

Review quality strategy for the Principled framework. Consult when working with code review checklists, review coverage, review summaries, or spec-driven review workflows. Covers the three checklist categories, severity classification, dual storage model, and quality gates.

Generate a spec-driven review checklist for a pull request. Extracts acceptance criteria from the associated plan, identifies relevant ADRs for the changed files, and produces a structured checklist. Posts the checklist as a PR comment and saves it locally per ADR-012.

Surface the proposals, plans, and ADRs relevant to a pull request's changed files. Maps files to modules, finds specification documents, and presents a concise summary of the review context.

Assess whether a pull request's review comments address the generated checklist items. Reads the checklist from PR comments and local files, maps review comments to checklist items, and reports coverage.

Generate a structured review summary for a pull request. Collects review state, builds a findings table linked to spec items, and produces a summary with coverage metrics and unresolved items.

Generate or update a CODEOWNERS file from the repository's module structure and git history. Maps module boundaries to code ownership using principled documentation structure as the guide. Use when setting up or refreshing code ownership rules.

Scaffold GitHub-specific configuration files aligned with the principled workflow. Creates issue templates, PR templates, actions workflows, and config files in the .github/ directory. Use when setting up a new repo or adding principled GitHub integration to an existing one.

GitHub integration strategy for the Principled framework. Consult when working with GitHub issues, pull requests, labels, CODEOWNERS, or .github/ templates in the context of the principled documentation pipeline. Covers issue-proposal mapping, PR-plan alignment, label taxonomy, and the GitHub-principled sync model.

Ingest a GitHub issue into the principled pipeline. Fetches the issue, determines what documents are needed (proposal, plan, or both), creates them pre-populated from issue content, and comments on the issue with links to the new documents on a feature branch.

Sync principled proposals and plans to GitHub issues. Creates or updates GitHub issues from proposal and plan documents, maintaining bidirectional references. Documents remain the source of truth.

Create and sync GitHub labels for the principled workflow lifecycle. Ensures all required labels exist with correct names, colors, and descriptions. Use when setting up a new repo or when the label taxonomy has been updated.

Validate task implementations by running the project's test suite, linters, and CI checks. Discovers test commands from common project patterns (package.json, Makefile, pytest, cargo, go) and reports pass/fail with details. Use after a sub-agent completes a task.

Decompose a DDD plan into executable tasks with dependency ordering. Reads a plan file, extracts phases, bounded contexts, and individual tasks, then creates a task manifest for orchestration. Use when you have an active DDD plan ready for implementation.

Merge a completed and validated task's worktree branch back to the working branch. Verifies checks passed, performs the merge, cleans up the worktree, and updates the task manifest. Directly invocable by users and by the orchestrate skill.

Execute a task from a DDD plan in an isolated git worktree. Reads task details from the manifest, embeds them in the prompt, and delegates to the impl-worker agent for worktree-isolated execution. Use after decomposing a plan into tasks.

Module documentation strategy for the Principled framework. Consult when working with proposals/, plans/, decisions/, architecture/ directories, README, CONTRIBUTING, CLAUDE, or INTERFACE files in any module. Covers the proposals → decisions → plans pipeline, naming conventions, lifecycle rules, DDD decomposition, and audience definitions.

Create a new Architectural Decision Record (ADR). Use when recording an architectural decision, either standalone or linked to an accepted proposal. Handles numbering and cross-referencing. ADRs are immutable after acceptance except for the superseded_by field. Once all ADRs for a proposal are accepted, create a plan via `/new-plan --from-proposal NNN`.

Create a DDD implementation plan from an accepted proposal. Plans implement proposals by decomposing work into bounded contexts, aggregates, and concrete tasks using domain-driven development. ADRs should be created before the plan to record key decisions. Use when an accepted proposal needs a tactical implementation breakdown before work begins.

Create a new proposal (RFC) document. Use when proposing a change, new feature, or architectural decision that needs team review. Handles numbering, naming, and template population. Use --root for cross-cutting proposals that affect multiple modules.