manifest.yaml

# SPDX-License-Identifier: MIT
# Copyright (c) PromptKit Contributors

# PromptKit — Manifest
# This file indexes all components in the library.
# The bootstrap prompt reads this manifest to discover available
# personas, protocols, formats, and task templates.

version: "0.2.0"

personas:
  - name: systems-engineer
    path: personas/systems-engineer.md
    description: >
      Senior systems engineer. Deep expertise in memory management,
      concurrency, performance, and debugging. Reasons from first principles.

  - name: security-auditor
    path: personas/security-auditor.md
    description: >
      Principal security engineer. Adversarial mindset. Specializes in
      vulnerability discovery, threat modeling, and secure design.

  - name: software-architect
    path: personas/software-architect.md
    description: >
      Staff software architect. System design, API contracts, tradeoff
      analysis, and long-term maintainability.

  - name: promptkit-contributor
    path: personas/promptkit-contributor.md
    description: >
      PromptKit contribution guide. Understands the library's architecture,
      conventions, and quality standards. Guides contributors through
      designing and building new components.

  - name: devops-engineer
    path: personas/devops-engineer.md
    description: >
      Senior DevOps / platform engineer. Deep expertise in CI/CD pipelines,
      release engineering, infrastructure-as-code, and platform APIs across
      GitHub Actions, Azure DevOps, GitLab CI, and other DevOps platforms.

  - name: reverse-engineer
    path: personas/reverse-engineer.md
    description: >
      Senior reverse engineer. Extracts specifications, contracts, and
      behavioral requirements from existing implementations. Separates
      essential behavior from implementation details.

  - name: specification-analyst
    path: personas/specification-analyst.md
    description: >
      Senior specification analyst. Cross-examines requirements, design,
      and validation artifacts for consistency, completeness, and
      traceability. Adversarial toward completeness claims.

  - name: workflow-arbiter
    path: personas/workflow-arbiter.md
    description: >
      Senior workflow arbiter. Evaluates multi-agent workflow progress,
      detects livelock and bikeshedding, and decides whether a
      coding/review/validation loop should continue or terminate.

  - name: implementation-engineer
    path: personas/implementation-engineer.md
    description: >
      Senior implementation engineer. Builds correct, maintainable code
      from specifications. Traces every implementation decision back to
      a requirement.

  - name: test-engineer
    path: personas/test-engineer.md
    description: >
      Senior test engineer. Writes thorough, specification-driven tests
      that verify every requirement and acceptance criterion. Prioritizes
      coverage breadth, negative cases, and boundary conditions.

protocols:
  guardrails:
    - name: anti-hallucination
      path: protocols/guardrails/anti-hallucination.md
      description: >
        Prevents fabrication. Enforces epistemic labeling (KNOWN/INFERRED/ASSUMED),
        uncertainty disclosure, and source attribution. Apply to all tasks.

    - name: self-verification
      path: protocols/guardrails/self-verification.md
      description: >
        Quality gate requiring the LLM to verify its own output before finalizing.
        Sampling checks, citation audits, coverage confirmation, consistency checks.

    - name: operational-constraints
      path: protocols/guardrails/operational-constraints.md
      description: >
        Governs how the LLM scopes work, uses tools, manages context, and
        prefers deterministic analysis. Prevents over-ingestion and ensures
        reproducibility.

  analysis:
    - name: memory-safety-c
      path: protocols/analysis/memory-safety-c.md
      description: >
        Memory safety analysis for C. Covers allocation/deallocation pairing,
        pointer lifecycle, buffer boundaries, and undefined behavior.
      language: C

    - name: memory-safety-rust
      path: protocols/analysis/memory-safety-rust.md
      description: >
        Memory safety analysis for Rust. Focuses on unsafe blocks, FFI
        boundaries, interior mutability, and resource leaks.
      language: Rust

    - name: thread-safety
      path: protocols/analysis/thread-safety.md
      description: >
        Concurrency analysis. Covers data races, deadlocks, atomicity
        violations, and thread lifecycle. Language-agnostic.

    - name: security-vulnerability
      path: protocols/analysis/security-vulnerability.md
      description: >
        Security vulnerability analysis. Trust boundaries, input validation,
        auth, crypto, and information disclosure. Language-agnostic.

  reasoning:
    - name: root-cause-analysis
      path: protocols/reasoning/root-cause-analysis.md
      description: >
        Systematic root cause analysis. Symptom characterization, hypothesis
        generation, evidence evaluation, and causal chain tracing.

    - name: requirements-elicitation
      path: protocols/reasoning/requirements-elicitation.md
      description: >
        Requirements extraction from natural language. Produces numbered,
        atomic, testable requirements with RFC 2119 keywords.

    - name: iterative-refinement
      path: protocols/reasoning/iterative-refinement.md
      description: >
        Protocol for revising documents through feedback cycles while
        preserving structural integrity, numbering, cross-references,
        and internal consistency.

    - name: promptkit-design
      path: protocols/reasoning/promptkit-design.md
      description: >
        Reasoning protocol for designing new PromptKit components. Scoping,
        component type selection, dependency analysis, and convention
        compliance.

    - name: devops-platform-analysis
      path: protocols/reasoning/devops-platform-analysis.md
      description: >
        Systematic reasoning about DevOps platform constructs: pipelines,
        triggers, jobs, environments, secrets, approvals, and artifacts.
        Platform-agnostic methodology with platform-specific instantiation.

    - name: requirements-from-implementation
      path: protocols/reasoning/requirements-from-implementation.md
      description: >
        Systematic reasoning protocol for deriving structured requirements
        from existing source code. Transforms code understanding into
        testable, atomic requirements with acceptance criteria.

    - name: traceability-audit
      path: protocols/reasoning/traceability-audit.md
      description: >
        Systematic cross-document comparison protocol for auditing
        requirements, design, and validation artifacts. Builds
        traceability matrices and classifies divergence using the
        specification-drift taxonomy.

    - name: code-compliance-audit
      path: protocols/reasoning/code-compliance-audit.md
      description: >
        Systematic protocol for auditing source code against requirements
        and design documents. Maps specification claims to code behavior
        and classifies findings using the specification-drift taxonomy
        (D8–D10).

    - name: test-compliance-audit
      path: protocols/reasoning/test-compliance-audit.md
      description: >
        Systematic protocol for auditing test code against a validation
        plan and requirements document. Maps test case definitions to
        test implementations and classifies findings using the
        specification-drift taxonomy (D11–D13).

    - name: integration-audit
      path: protocols/reasoning/integration-audit.md
      description: >
        Systematic protocol for auditing cross-component integration
        points. Maps integration flows across component boundaries,
        verifies interface contracts, and checks integration test
        coverage. Classifies findings using the specification-drift
        taxonomy (D14–D16).

    - name: rfc-extraction
      path: protocols/reasoning/rfc-extraction.md
      description: >
        Systematic protocol for extracting structured requirements from
        RFCs and internet-drafts. Handles normative language (RFC 2119),
        state machines, cross-RFC dependencies, ABNF grammars, and
        IANA/security considerations.

    - name: invariant-extraction
      path: protocols/reasoning/invariant-extraction.md
      description: >
        Systematic protocol for extracting structured invariants
        (constraints, state machines, timing assumptions, ordering
        rules, error conditions) from specifications or source code.
        Produces a dense, filtered subset of a full requirements
        extraction.

    - name: workflow-arbitration
      path: protocols/reasoning/workflow-arbitration.md
      description: >
        Protocol for evaluating progress in a multi-agent coding
        workflow. Determines whether reviewer findings are valid,
        coder responses are adequate, and whether the workflow should
        continue or terminate.

    - name: requirements-reconciliation
      path: protocols/reasoning/requirements-reconciliation.md
      description: >
        Systematic protocol for reconciling multiple requirements
        documents from different sources into a unified specification.
        Classifies each requirement by cross-source compatibility
        (Universal, Majority, Divergent, Extension).

formats:
  - name: requirements-doc
    path: formats/requirements-doc.md
    produces: requirements-document
    description: >
      Structured requirements document with numbered REQ-IDs, acceptance
      criteria, constraints, assumptions, and risks.

  - name: design-doc
    path: formats/design-doc.md
    produces: design-document
    consumes: requirements-document
    description: >
      Software design document with architecture, API contracts, data models,
      tradeoff analysis, and open questions.

  - name: validation-plan
    path: formats/validation-plan.md
    produces: validation-plan
    consumes: requirements-document
    description: >
      Test and validation plan with traceability matrix, test cases,
      risk prioritization, and pass/fail criteria.

  - name: investigation-report
    path: formats/investigation-report.md
    produces: investigation-report
    description: >
      Investigation report with findings, root cause analysis, evidence,
      remediation plan, and prevention recommendations.

  - name: multi-artifact
    path: formats/multi-artifact.md
    produces: artifact-set
    description: >
      Multi-file output format for tasks producing multiple deliverables
      (structured data, reports, coverage logs). Defines artifact manifests,
      per-artifact schemas, and cross-artifact consistency rules.

  - name: promptkit-pull-request
    path: formats/promptkit-pull-request.md
    produces: promptkit-contribution
    description: >
      Output format for PromptKit contributions. Produces PR-ready component
      files, manifest update, and pull request description.

  - name: pipeline-spec
    path: formats/pipeline-spec.md
    produces: pipeline-spec
    description: >
      CI/CD pipeline specification with platform-specific YAML, design
      rationale, configuration requirements, and deployment notes.

  - name: triage-report
    path: formats/triage-report.md
    produces: triage-report
    description: >
      Prioritized triage report for issues, pull requests, or work items.
      Classifies items by priority, effort, and recommended action.

  - name: release-notes
    path: formats/release-notes.md
    produces: release-notes
    description: >
      Structured release notes with changelog, breaking changes, upgrade
      instructions, and contributor acknowledgment.

  - name: agent-instructions
    path: formats/agent-instructions.md
    produces: agent-instruction-file
    description: >
      Output format for persistent agent instruction files. For GitHub
      Copilot, produces composable skill files under
      .github/instructions/*.instructions.md with applyTo targeting.
      Also supports Claude Code (CLAUDE.md) and Cursor (.cursorrules).

  - name: implementation-plan
    path: formats/implementation-plan.md
    produces: implementation-plan
    description: >
      Output format for implementation and refactoring plans. Task
      breakdown, dependency ordering, risk assessment, and verification
      strategy.

  - name: north-star-document
    path: formats/north-star-document.md
    produces: north-star-document
    description: >
      Strategic north-star or architectural vision document. Describes
      the desired end state, guiding principles, and transition
      considerations — not the implementation plan.

taxonomies:
  - name: stack-lifetime-hazards
    path: taxonomies/stack-lifetime-hazards.md
    domain: memory-safety
    description: >
      Classification scheme (H1-H5) for stack lifetime and memory escape
      hazards at system boundaries. Covers stack address escape, async
      pend/complete lifetime violations, and writable views of read-only data.

  - name: specification-drift
    path: taxonomies/specification-drift.md
    domain: specification-traceability
    description: >
      Classification scheme (D1-D16) for specification drift across
      requirements, design, validation, code, test, and integration
      artifacts. Covers untraced requirements, orphaned design decisions,
      assumption drift, coverage failures, code/test compliance gaps,
      and cross-component integration drift.

templates:
  document-authoring:
    - name: author-requirements-doc
      path: templates/author-requirements-doc.md
      description: >
        Generate a requirements document from a natural language description.
        Single-shot generation. For complex/ambiguous projects, use
        interactive-design instead.
      persona: software-architect
      protocols: [anti-hallucination, self-verification, requirements-elicitation]
      format: requirements-doc
      pipeline_position: 1

    - name: interactive-design
      path: templates/interactive-design.md
      description: >
        Multi-phase interactive design session. Phase 1: reason, question,
        and challenge before generating. Phase 2: generate when told.
        Phase 3: iterative refinement. Use for complex or ambiguous projects.
      persona: configurable
      protocols: [anti-hallucination, self-verification, requirements-elicitation, iterative-refinement]
      format: requirements-doc

    - name: author-north-star
      path: templates/author-north-star.md
      description: >
        Interactive authoring of a north-star or architectural vision
        document. Evidence-grounded, section-by-section drafting with
        user review. Use for strategic direction documents.
      persona: software-architect
      protocols: [anti-hallucination, self-verification]
      format: north-star-document

    - name: author-design-doc
      path: templates/author-design-doc.md
      description: >
        Generate a design document that addresses a requirements document.
      persona: software-architect
      protocols: [anti-hallucination, self-verification]
      format: design-doc
      pipeline_position: 2
      requires: requirements-document

    - name: author-validation-plan
      path: templates/author-validation-plan.md
      description: >
        Generate a validation plan covering all requirements.
      persona: systems-engineer
      protocols: [anti-hallucination, self-verification]
      format: validation-plan
      pipeline_position: 3
      requires: requirements-document

    - name: reverse-engineer-requirements
      path: templates/reverse-engineer-requirements.md
      description: >
        Reverse-engineer a structured requirements document from existing
        source code. Analyzes implementation to extract behavioral contracts,
        API specifications, and invariants.
      persona: reverse-engineer
      protocols: [anti-hallucination, self-verification, operational-constraints, requirements-from-implementation]
      format: requirements-doc

    - name: audit-traceability
      path: templates/audit-traceability.md
      description: >
        Audit requirements, design, and validation documents for
        specification drift. Cross-checks traceability, assumption
        consistency, constraint propagation, and coverage completeness.
      persona: specification-analyst
      protocols: [anti-hallucination, self-verification, traceability-audit]
      taxonomies: [specification-drift]
      format: investigation-report
      pipeline_position: 4
      requires: [requirements-document, validation-plan]

    - name: audit-code-compliance
      path: templates/audit-code-compliance.md
      description: >
        Audit source code against requirements and design documents.
        Detects unimplemented requirements, undocumented behavior, and
        constraint violations.
      persona: specification-analyst
      protocols: [anti-hallucination, self-verification, operational-constraints, code-compliance-audit]
      taxonomies: [specification-drift]
      format: investigation-report
      requires: requirements-document

    - name: audit-test-compliance
      path: templates/audit-test-compliance.md
      description: >
        Audit test code against a validation plan and requirements
        document. Detects unimplemented test cases, missing acceptance
        criterion assertions, and assertion mismatches.
      persona: specification-analyst
      protocols: [anti-hallucination, self-verification, operational-constraints, test-compliance-audit]
      taxonomies: [specification-drift]
      format: investigation-report
      requires: [requirements-document, validation-plan]

    - name: audit-integration-compliance
      path: templates/audit-integration-compliance.md
      description: >
        Audit cross-component integration points against an integration
        specification and per-component specs. Detects unspecified
        integration flows, interface contract mismatches, and untested
        integration paths.
      persona: specification-analyst
      protocols: [anti-hallucination, self-verification, operational-constraints, integration-audit]
      taxonomies: [specification-drift]
      format: investigation-report
      requires: requirements-document

  standards:
    - name: extract-rfc-requirements
      path: templates/extract-rfc-requirements.md
      description: >
        Extract structured requirements from an RFC or internet-draft.
        Normalizes normative language, state machines, message formats,
        and cross-RFC dependencies into a requirements document.
      persona: specification-analyst
      protocols: [anti-hallucination, self-verification, rfc-extraction]
      format: requirements-doc

    - name: reconcile-requirements
      path: templates/reconcile-requirements.md
      description: >
        Reconcile multiple requirements documents from different sources
        (RFCs, implementations, specifications) into a unified spec.
        Classifies requirements by cross-source compatibility.
      persona: specification-analyst
      protocols: [anti-hallucination, self-verification, requirements-reconciliation]
      format: requirements-doc

    - name: extract-invariants
      path: templates/extract-invariants.md
      description: >
        Extract structured invariants (constraints, state machines,
        timing assumptions, error conditions) from a specification or
        source code. Produces a dense, filtered subset of a full
        requirements extraction.
      persona: specification-analyst
      protocols: [anti-hallucination, self-verification, invariant-extraction]
      format: requirements-doc

  code-generation:
    - name: author-implementation-prompt
      path: templates/author-implementation-prompt.md
      description: >
        Produce a structured prompt for a coding agent to generate
        spec-compliant implementation code. Pairs with
        audit-code-compliance for a generate/verify loop.
      persona: implementation-engineer
      protocols: [anti-hallucination, self-verification]
      format: requirements-doc
      requires: requirements-document

    - name: author-test-prompt
      path: templates/author-test-prompt.md
      description: >
        Produce a structured prompt for a coding agent to generate
        spec-compliant test code. Pairs with audit-test-compliance
        for a generate/verify loop.
      persona: test-engineer
      protocols: [anti-hallucination, self-verification]
      format: validation-plan
      requires: [requirements-document, validation-plan]

    - name: author-workflow-prompts
      path: templates/author-workflow-prompts.md
      description: >
        Generate prompt assets for a multi-agent coding workflow:
        coder, reviewer, validator, and orchestrator prompts.
        Designed for external orchestrators — PromptKit produces
        the prompts, not the runtime.
      persona: workflow-arbiter
      protocols: [anti-hallucination, self-verification, workflow-arbitration]
      format: multi-artifact
      requires: requirements-document

  investigation:
    - name: investigate-bug
      path: templates/investigate-bug.md
      description: >
        Investigate a bug from a problem description. Apply root cause
        analysis and produce an investigation report.
      persona: systems-engineer
      protocols: [anti-hallucination, self-verification, operational-constraints, root-cause-analysis]
      taxonomies: [stack-lifetime-hazards]
      format: investigation-report

    - name: investigate-security
      path: templates/investigate-security.md
      description: >
        Security audit of code or a system component. Systematic
        vulnerability analysis with severity classification.
      persona: security-auditor
      protocols: [anti-hallucination, self-verification, operational-constraints, security-vulnerability]
      taxonomies: [stack-lifetime-hazards]
      format: investigation-report

  code-analysis:
    - name: review-code
      path: templates/review-code.md
      description: >
        Thorough code review for correctness, safety, security,
        and maintainability. Supports additional analysis protocols.
      persona: systems-engineer
      protocols: [anti-hallucination, self-verification, operational-constraints]
      taxonomies: [stack-lifetime-hazards]
      format: investigation-report

  planning:
    - name: plan-implementation
      path: templates/plan-implementation.md
      description: >
        Decompose a project into an actionable implementation plan
        with tasks, dependencies, and risk assessment.
      persona: software-architect
      protocols: [anti-hallucination, self-verification]
      format: implementation-plan

    - name: plan-refactoring
      path: templates/plan-refactoring.md
      description: >
        Plan a safe, incremental refactoring with step-by-step
        changes that maintain correctness at each step.
      persona: software-architect
      protocols: [anti-hallucination, self-verification]
      format: implementation-plan

  agent-authoring:
    - name: author-agent-instructions
      path: templates/author-agent-instructions.md
      description: >
        Assemble PromptKit components (persona, protocols) into composable
        agent skill files. For GitHub Copilot, produces individual
        .github/instructions/*.instructions.md files with applyTo targeting.
        Also supports Claude Code (CLAUDE.md) and Cursor (.cursorrules).
      persona: promptkit-contributor
      protocols: [anti-hallucination, self-verification]
      format: agent-instructions

  contribution:
    - name: extend-library
      path: templates/extend-library.md
      description: >
        Guide a contributor through designing and building new PromptKit
        components. Interactive workflow producing PR-ready files.
      persona: promptkit-contributor
      protocols: [anti-hallucination, self-verification, promptkit-design]
      format: promptkit-pull-request

  devops:
    - name: author-pipeline
      path: templates/author-pipeline.md
      description: >
        Generate a production-ready CI/CD pipeline for a given application
        and target platform. Supports GitHub Actions, Azure DevOps, GitLab CI.
      persona: devops-engineer
      protocols: [anti-hallucination, self-verification, devops-platform-analysis]
      format: pipeline-spec

    - name: triage-issues
      path: templates/triage-issues.md
      description: >
        Triage and prioritize open issues or work items. Classify by
        priority and effort, identify patterns, recommend a workflow.
      persona: devops-engineer
      protocols: [anti-hallucination, self-verification]
      format: triage-report

    - name: triage-pull-requests
      path: templates/triage-pull-requests.md
      description: >
        Triage open pull requests to identify which need review, are stale,
        have conflicts, or are ready to merge. Prioritize review effort.
      persona: devops-engineer
      protocols: [anti-hallucination, self-verification]
      format: triage-report

    - name: root-cause-ci-failure
      path: templates/root-cause-ci-failure.md
      description: >
        Investigate a failing CI/CD pipeline run. Analyze logs, pipeline
        configuration, and platform behavior. Produce an investigation report.
      persona: devops-engineer
      protocols: [anti-hallucination, self-verification, root-cause-analysis, devops-platform-analysis]
      format: investigation-report

    - name: author-release
      path: templates/author-release.md
      description: >
        Generate structured release notes from commits, PRs, and issues
        between two versions. Changelog, breaking changes, upgrade instructions.
      persona: devops-engineer
      protocols: [anti-hallucination, self-verification]
      format: release-notes

    - name: review-infrastructure
      path: templates/review-infrastructure.md
      description: >
        Review infrastructure-as-code (Terraform, Bicep, ARM, Pulumi,
        CloudFormation) for correctness, security, and best practices.
      persona: devops-engineer
      protocols: [anti-hallucination, self-verification, security-vulnerability]
      format: investigation-report

pipelines:
  document-lifecycle:
    description: >
      Full document lifecycle from requirements through validation.
      Each stage produces an artifact consumed by the next.
    stages:
      - template: author-requirements-doc
        produces: requirements-document
      - template: author-design-doc
        consumes: requirements-document
        produces: design-document
      - template: author-validation-plan
        consumes: requirements-document
        produces: validation-plan
      - template: audit-traceability
        consumes: [requirements-document, validation-plan]
        produces: investigation-report