schema_version: "1"

# Each component has:
#   id:             Unique identifier used by install.sh
#   type:           constitution | rule | skill | agent | workflow
#   path:           Path relative to repo root
#   name:           Human-readable name
#   description:    What this component provides
#   category:       Logical grouping (core, planning, testing, data-ml, security, ci-cd, etc.)
#   platforms:      Which agent platforms this works with
#   dependencies:   Other component IDs this requires
#   install_target: Where to copy relative to the target project root ("." = project root)

components:
  - id: constitution
    type: constitution
    path: CONSTITUTION.md
    name: Engineering Constitution
    description: >
      19-section engineering constitution covering supreme principles,
      architecture, error handling, testing, agentic engineering, planning,
      security, git discipline, data/ML pipelines, and language-specific rules.
    category: core
    platforms: [generic]
    dependencies: []
    install_target: "."

  - id: github-actions-claude
    type: skill
    path: skills/github-actions-claude
    name: GitHub Actions + Claude
    description: >
      Pattern catalog for authoring, debugging, and testing GitHub Actions
      workflows that use anthropics/claude-code-action. Covers permissions,
      tool allowlists, model selection, output patterns, and failure modes.
    category: ci-cd
    platforms: [generic]
    dependencies: []
    install_target: skills

  - id: conda-forge-publish
    type: skill
    path: skills/conda-forge-publish
    name: conda-forge Publish
    description: >
      End-to-end workflow for publishing Python packages to conda-forge.
      Covers rattler-build v1 recipe authoring, staged-recipes PR submission,
      feedstock maintenance, and common gotchas (entry_points, python_min,
      cross-platform dep availability).
    category: packaging
    platforms: [generic]
    dependencies: []
    install_target: skills

  - id: docs-site
    type: skill
    path: skills/docs-site
    name: Documentation Site
    description: >
      Set up MkDocs + Material documentation with auto-generated API reference
      for Python packages. Covers mkdocs.yml configuration, mkdocstrings setup,
      docs/ skeleton, and GitHub Pages deployment workflow.
    category: documentation
    platforms: [generic]
    dependencies: [wf-docs-deploy, wf-docs-update]
    install_target: skills

  - id: docs-manager
    type: skill
    path: skills/docs-manager
    name: Docs Manager
    description: >
      Set up and operate a GitHub-based docs repository for a software team.
      Covers the two-flow model (Issues = trackable work, Markdown = permanent records),
      label taxonomy, Obsidian Templater templates, automated issue sync, Claude-powered
      PR review, weekly code->docs sync, and GitHub Pages deployment.
    category: documentation
    platforms: [github-actions]
    dependencies: [wf-issue-triage, wf-claude-mention, wf-issue-sync, wf-project-sync, wf-docs-review, wf-code-sync-weekly]
    install_target: skills

  - id: skill-creator
    type: skill
    path: skills/skill-creator
    name: Skill Creator
    description: >
      Create new skills, iteratively improve existing skills, and measure
      skill performance with eval benchmarks and description optimization.
      Includes grader, comparator, and analyzer subagents, an eval viewer
      webapp, and automated description triggering tests.
    category: meta
    platforms: [generic]
    dependencies: []
    install_target: skills
    license: Apache-2.0
    upstream: https://github.com/anthropics/skills/tree/main/skills/skill-creator

  - id: frontend-design
    type: skill
    path: skills/frontend-design
    name: Frontend Design
    description: >
      Frontend design aesthetics and UI/UX guidance: typography, color, motion,
      spatial composition, and component architecture patterns for web interfaces.
      Covers anti-AI-slop patterns, React 19 notes, and a pre-ship checklist.
    category: frontend
    platforms: [generic]
    dependencies: []
    install_target: skills

  - id: fastapi-fullstack
    type: skill
    path: skills/fastapi-fullstack
    name: FastAPI Fullstack
    description: >
      Scaffold a production-grade FastAPI + React full-stack project from the
      official FastAPI template. PostgreSQL, JWT auth, Docker Compose, Traefik,
      and GitHub Actions CI/CD. Includes an init script that clones, renames,
      and configures the project interactively.
    category: backend
    platforms: [generic]
    dependencies: []
    install_target: skills

  - id: fastapi-minimal
    type: skill
    path: skills/fastapi-minimal
    name: FastAPI Minimal
    description: >
      Scaffold a minimal async FastAPI + SQLModel project with SQLite, Alembic
      migrations, pydantic-settings config, and pytest-asyncio tests. No Docker
      required. Upgradeable to PostgreSQL by swapping the DATABASE_URL.
    category: backend
    platforms: [generic]
    dependencies: []
    install_target: skills

  - id: web-artifacts-builder
    type: skill
    path: skills/web-artifacts-builder
    name: Web Artifacts Builder
    description: >
      Build complex React artifacts (React + TypeScript + Tailwind CSS 3 +
      shadcn/ui, 40+ components pre-installed) and bundle them to a single
      self-contained HTML file for display in conversation. Includes init
      and bundle scripts.
    category: frontend
    platforms: [generic]
    dependencies: [frontend-design]
    install_target: skills

  - id: markdown-convert
    type: skill
    path: skills/markdown-convert
    name: Markdown Convert
    description: >
      Convert Markdown files to PDF or DOCX, stripping Obsidian-specific
      syntax (wikilinks, embeds, callouts, Relations section) before export.
      Powered by the obsidian-export PyPI library. Supports Mermaid diagram
      rendering and custom LaTeX brand profiles.
    category: documentation
    platforms: [generic]
    dependencies: []
    install_target: skills

  - id: excel-analyst
    type: skill
    path: skills/excel-analyst
    name: Excel Analyst
    description: >
      Build professional Excel financial models (P&L, DCF, Budget vs Actuals,
      Scenario Analysis) from declarative YAML specs. Generates .xlsx workbooks
      with named ranges, styled sheets, and Excel formulas via the excel-model
      PyPI package.
    category: data-ml
    platforms: [generic]
    dependencies: []
    install_target: skills

  - id: academic-research
    type: skill
    path: skills/academic-research
    name: Academic Research
    description: >
      Scripts for academic literature review — search PubMed, Semantic Scholar,
      and Zotero; scaffold paper knowledge notes from metadata JSON; download
      and extract PDFs; export BibTeX from existing paper notes.
    category: research
    platforms: [generic]
    dependencies: []
    install_target: skills

  # --- Agents ---

  - id: engineering-reviewer
    type: agent
    path: agents/engineering-reviewer.md
    name: Engineering Reviewer
    description: >
      Read-only compliance reviewer that audits code against the 11 engineering
      principles and produces a structured report with PASS/VIOLATIONS/SUMMARY
      sections and CLEAN/MINOR/MAJOR/CRITICAL severity ratings.
    category: quality
    platforms: [generic]
    dependencies: [engineering-principles]
    install_target: agents

  - id: software-engineer
    type: agent
    path: agents/software-engineer.md
    name: Software Engineer
    description: >
      Senior software engineer agent for coding-heavy tasks: new Python packages,
      multi-file refactors, TDD cycles, CLI tools, and debugging. Enforces the
      11 engineering principles inline. Supports FastAPI, web artifacts, and
      general Python development.
    category: engineering
    platforms: [generic]
    dependencies: [engineering-principles]
    install_target: agents

  - id: literature-researcher
    type: agent
    path: agents/literature-researcher.md
    name: Literature Researcher
    description: >
      Academic literature review agent — quick scan or deep dive on any
      research topic. Uses Python scripts for PubMed, Semantic Scholar,
      and Zotero search plus native WebSearch/WebFetch.
    category: research
    platforms: [generic]
    dependencies: [academic-research]
    install_target: agents

  # --- Rules ---

  - id: engineering-principles
    type: rule
    path: rules/engineering-principles.md
    name: Engineering Principles
    description: >
      Non-negotiable engineering principles: KISS, DRY, no default arguments,
      fail fast, config-driven, modular, TDD, property-based testing.
    category: core
    platforms: [generic]
    dependencies: [constitution]
    install_target: rules

  - id: planning-protocol
    type: rule
    path: rules/planning-protocol.md
    name: Planning Protocol
    description: >
      Task complexity assessment, structured question-asking, scope validation,
      re-planning triggers, and planning anti-patterns.
    category: planning
    platforms: [generic]
    dependencies: [constitution]
    install_target: rules

  - id: data-ml-principles
    type: rule
    path: rules/data-ml-principles.md
    name: Data and ML Principles
    description: >
      Notebooks vs source, experiment provenance, feature hygiene, schema safety,
      data pipeline testing, and model monitoring in production.
    category: data-ml
    platforms: [generic]
    dependencies: [constitution]
    install_target: rules

  - id: git-commit-conventions
    type: rule
    path: rules/git-commit-conventions.md
    name: Git Commit Conventions
    description: >
      Commit message format (type-prefix + imperative), staging rules,
      branch naming conventions.
    category: git
    platforms: [generic]
    dependencies: []
    install_target: rules

  - id: workspace-portability
    type: rule
    path: rules/workspace-portability.md
    name: Workspace Portability
    description: >
      No hardcoded paths, config-derived workspace roots, relative path
      resolution against config file directory.
    category: core
    platforms: [generic]
    dependencies: []
    install_target: rules

  - id: no-implicit-assumptions
    type: rule
    path: rules/no-implicit-assumptions.md
    name: No Implicit Assumptions
    description: >
      Never attribute responsibilities or decisions to specific people
      unless explicitly confirmed. Use role-based language by default.
    category: agentic
    platforms: [generic]
    dependencies: []
    install_target: rules

  - id: source-citations
    type: rule
    path: rules/source-citations.md
    name: Source Citations
    description: >
      Citation conventions for external claims in knowledge docs: inline
      links, Sources sections, internal cross-references.
    category: documentation
    platforms: [generic]
    dependencies: []
    install_target: rules

  - id: git-submodules
    type: rule
    path: rules/git-submodules.md
    name: Git Submodules
    description: >
      Decision framework for when to use submodules vs package deps,
      directory conventions, add/update/remove commands, common pitfalls.
    category: git
    platforms: [generic]
    dependencies: []
    install_target: rules

  - id: mermaid-obsidian
    type: rule
    path: rules/mermaid-obsidian.md
    name: Mermaid Obsidian Conventions
    description: >
      Mermaid diagram conventions for Obsidian compatibility: line breaks,
      subgraph labels, node IDs, arrow labels.
    category: documentation
    platforms: [generic]
    dependencies: []
    install_target: rules

  # --- Workflows (Dark Factory) ---

  - id: wf-claude-mention
    type: workflow
    path: workflows/claude-mention.yml
    name: Claude Mention Handler
    description: >
      Interactive @claude mentions on issues and PRs. Responds to @claude
      in comments, reviews, and issue bodies.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-pr-code-review
    type: workflow
    path: workflows/pr-code-review.yml
    name: PR Code Review
    description: >
      Automatic code review on pull requests using the claude-code-plugins
      code-review plugin. Reviews bot-created PRs too.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-issue-triage
    type: workflow
    path: workflows/issue-triage.yml
    name: Issue Auto-Triage
    description: >
      Automatically classifies and labels newly opened issues. Applies
      type, priority, and status labels based on CLAUDE.md taxonomy.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-pr-docs-check
    type: workflow
    path: workflows/pr-docs-check.yml
    name: PR Documentation Check
    description: >
      Checks PRs for documentation compliance: missing docstrings,
      README updates, changelog entries.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-issue-implement
    type: workflow
    path: workflows/issue-implement.yml
    name: Issue Implementer
    description: >
      Implements issues labeled claude:implement as PRs. Creates branch,
      implements changes, runs tests, and opens a PR.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-dep-audit
    type: workflow
    path: workflows/dep-audit.yml
    name: Dependency Audit
    description: >
      Weekly dependency and vulnerability audit. Creates issues for
      outdated deps and known vulnerabilities.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-security-scan
    type: workflow
    path: workflows/security-scan.yml
    name: Security Scan
    description: >
      Weekly security assessment. Scans for hardcoded secrets, injection
      vulnerabilities, insecure patterns, and missing input validation.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-code-quality
    type: workflow
    path: workflows/code-quality.yml
    name: Code Quality Check
    description: >
      Weekly code quality assessment. Finds long files, high complexity,
      code duplication, dead code, and missing type hints.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-test-coverage
    type: workflow
    path: workflows/test-coverage.yml
    name: Test Coverage Analysis
    description: >
      Weekly test coverage analysis. Identifies files below coverage
      threshold and suggests test cases for uncovered code paths.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-docs-freshness
    type: workflow
    path: workflows/docs-freshness.yml
    name: Documentation Freshness Check
    description: >
      Monthly documentation staleness check. Flags docs not updated
      in 90+ days and README drift from actual CLI/API.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-workflow-upgrade
    type: workflow
    path: workflows/workflow-upgrade.yml
    name: Workflow Upgrade Check
    description: >
      Monthly GitHub Actions version check. Flags outdated action
      versions and deprecated inputs.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-pr-autofix
    type: workflow
    path: workflows/pr-autofix.yml
    name: PR Auto-Fix
    description: >
      Automatically fixes CI failures on agent-created PRs. Downloads failure
      logs, runs Claude to fix code, pushes fixes (up to 3 attempts). Promotes
      draft PRs to ready-for-review when CI passes.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude]
    install_target: .github/workflows

  - id: wf-docs-deploy
    type: workflow
    path: workflows/docs-deploy.yml
    name: Docs Deploy
    description: >
      Build MkDocs documentation and deploy to GitHub Pages. Builds on every
      push and PR (catch broken docs early), deploys only on push to main.
      Uses official actions/deploy-pages (no PAT or gh-pages branch needed).
    category: ci-cd
    platforms: [github-actions]
    dependencies: []
    install_target: .github/workflows

  - id: wf-docs-update
    type: workflow
    path: workflows/docs-update.yml
    name: Docs Update
    description: >
      Keep docs/ in sync with source code. Runs weekly and on manual
      dispatch. Uses Claude to detect drift between code and documentation,
      then opens a PR with updates. Skips if an open docs-update PR
      already exists.
    category: ci-cd
    platforms: [github-actions]
    dependencies: [github-actions-claude, wf-docs-deploy]
    install_target: .github/workflows

  - id: wf-issue-sync
    type: workflow
    path: workflows/issue-sync.yml
    name: Issue Sync
    description: >
      Mirrors GitHub Issues to markdown snapshots in sync/issues/. Triggered on
      sync-to-docs label, issue close, weekly resync, and manual dispatch.
      Enables Obsidian vault search over issue content.
    category: documentation
    platforms: [github-actions]
    dependencies: [docs-manager]
    install_target: .github/workflows

  - id: wf-project-sync
    type: workflow
    path: workflows/project-sync.yml
    name: Project Board Sync
    description: >
      Mirrors GitHub Projects v2 board state to sync/projects/ as a kanban
      markdown snapshot. Runs daily. Requires ORG_PROJECTS_TOKEN secret with
      read:org and read:project scopes.
    category: documentation
    platforms: [github-actions]
    dependencies: [docs-manager]
    install_target: .github/workflows

  - id: wf-docs-review
    type: workflow
    path: workflows/docs-review.yml
    name: Docs Review
    description: >
      Claude reviews PRs that touch projects/ or sops/. Checks YAML frontmatter,
      naming conventions, absence of vault syntax, and required sections in
      meeting notes and decision records.
    category: documentation
    platforms: [github-actions]
    dependencies: [github-actions-claude, docs-manager]
    install_target: .github/workflows

  - id: wf-code-sync-weekly
    type: workflow
    path: workflows/code-sync-weekly.yml
    name: Code Sync Weekly
    description: >
      Weekly cross-repo sync: queries registered code repos for merged PRs, releases,
      and docs-needed issues, then opens a draft PR updating architecture docs and
      status files. Requires DOCS_WRITE_TOKEN and CLAUDE_CODE_OAUTH_TOKEN.
    category: documentation
    platforms: [github-actions]
    dependencies: [github-actions-claude, docs-manager]
    install_target: .github/workflows

  - id: wf-factory-orchestrator
    type: workflow
    path: workflows/factory-orchestrator.yml
    name: Factory Orchestrator
    description: >
      Hourly sweep for orphaned issues (claude:implement label set by
      GITHUB_TOKEN but never triggered). Re-labels with FACTORY_PAT to
      fire issue-implement. Retries blocked issues after 3 days. Posts
      dashboard status summary. Pure shell, no LLM cost.
    category: ci-cd
    platforms: [github-actions]
    dependencies: []
    install_target: .github/workflows