18 KiB
18 KiB
21 — Initial seed catalog
The product roadmap contains 72 distinct playbook concepts. All 28 P0 entries are delivered as publishable package directories under content/playbooks/. P1 and P2 entries remain explicitly labeled authored backlog. The machine-readable source is catalog/seed-catalog.yaml; runtime delivery rules are in docs/36-seed-content-delivery.md.
Catalog design rules
- Every entry solves a distinct recurring development job.
- Audit and plan playbooks do not accidentally authorize code changes.
- High-risk work defaults to planning or evidence-heavy verification.
- Generic titles remain repository-aware through profiles and typed inputs.
- A catalog entry is not
Validateduntil a full package and evaluation evidence exist.
Priority summary
| Priority | Meaning | Count |
|---|---|---|
| P0 | Publishable launch catalog | 28 |
| P1 | Early expansion | 36 |
| P2 | Specialized expansion | 8 |
Repository Understanding
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Repository Inventory and Map (repository-inventory) |
guided | low | diagnose | Build an evidence-based inventory of applications, services, packages, data stores, deployment assets and key relationships without changing the repository. |
| P1 | Reconstruct Current Architecture (architecture-reconstruction) |
run-pack | low | diagnose | Infer and document the current architecture, boundaries and data flows from code and configuration while distinguishing observation from inference. |
| P1 | Trace a Critical User or Data Flow (critical-flow-tracing) |
guided | low | diagnose | Follow one critical flow across frontend, API, persistence and external integrations to expose behavior, dependencies and failure points. |
| P0 | Generate Developer Onboarding Guide (onboarding-documentation) |
run-pack | low | plan | Create accurate setup, architecture and contribution guidance from repository evidence without inventing unavailable commands. |
| P0 | Generate Repository AGENTS.md Guidance (agents-instructions) |
guided | moderate | plan | Create reviewed persistent Codex instructions from real repository commands, protected paths and engineering policies. |
| P1 | Documentation-to-Code Drift Audit (documentation-code-drift) |
guided | low | diagnose | Compare setup, API, configuration and operational documentation with actual implementation and report stale or misleading content. |
| P2 | Dependency Surface Map (dependency-surface-map) |
guided | low | diagnose | Map internal package dependencies and important external integrations to reveal coupling, cycles and critical dependency paths. |
| P1 | Create Evidence-Based Technical Debt Register (technical-debt-register) |
run-pack | low | plan | Convert observable maintainability, reliability and operational issues into a prioritized register with impact, evidence and remediation shape. |
Audits
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Repository Health Audit (repository-health-audit) |
guided | low | diagnose | Assess repository hygiene, documentation, testing, dependency management, release readiness and agent readiness without making changes. |
| P1 | Architecture Quality Audit (architecture-audit) |
run-pack | moderate | diagnose | Review boundaries, coupling, data ownership, dependency direction and operational fit against the repository’s stated goals. |
| P0 | Frontend UX and Interaction Audit (frontend-ux-audit) |
guided | low | diagnose | Evaluate hierarchy, interaction clarity, responsive behavior, empty states, consistency and perceived product quality using the running application where available. |
| P0 | Accessibility Audit (accessibility-audit) |
guided | moderate | diagnose | Audit semantic structure, keyboard use, focus, forms, contrast, motion and assistive-technology behavior for selected user flows. |
| P1 | Application Performance Audit (performance-audit) |
run-pack | moderate | diagnose | Identify measurable frontend, backend, database and build-performance bottlenecks before proposing targeted improvements. |
| P1 | API Contract and Compatibility Audit (api-contract-audit) |
guided | moderate | diagnose | Assess API consistency, validation, errors, versioning, idempotency and backwards-compatibility risks. |
| P1 | Database Design and Query Audit (database-audit) |
run-pack | high | diagnose | Review schema design, indexes, query patterns, transactions, migrations and data-integrity controls using available evidence. |
| P0 | Docker and Self-Hosting Audit (docker-self-hosting-audit) |
guided | moderate | diagnose | Review container security, image size, health checks, persistence, configuration and operability for self-hosted deployment. |
| P1 | Logging and Observability Audit (observability-audit) |
guided | moderate | diagnose | Assess whether logs, metrics, health checks and audit events support troubleshooting without leaking sensitive data. |
| P0 | Production Readiness Audit (production-readiness-audit) |
run-pack | high | plan | Evaluate deployability, security, migrations, recovery, monitoring, documentation and release evidence before production use. |
Bugfixing
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Root-Cause Bug Fix (root-cause-bugfix) |
guided | moderate | verify | Reproduce a reported defect, identify its root cause, add regression evidence and implement the smallest structural fix. |
| P1 | Flaky Test Investigation and Repair (flaky-test-repair) |
guided | moderate | verify | Measure, isolate and fix nondeterministic tests without masking real product defects or adding arbitrary retries. |
| P0 | Build Failure Recovery (build-failure-recovery) |
guided | moderate | verify | Diagnose and repair a failing build while preserving intended build checks and avoiding broad dependency churn. |
| P1 | Dependency Conflict Repair (dependency-conflict-repair) |
guided | moderate | verify | Resolve incompatible or duplicated dependencies with a minimal, explainable dependency graph change and full install/build validation. |
| P1 | Frontend State and Lifecycle Bug Fix (frontend-state-bug) |
guided | moderate | verify | Trace incorrect UI state across events, effects, cache and asynchronous boundaries before implementing a regression-tested repair. |
| P1 | External API Integration Failure (api-integration-failure) |
guided | high | verify | Diagnose request, authentication, schema, retry and error-handling failures without exposing credentials or weakening security. |
| P2 | Database Concurrency Bug Investigation (database-concurrency-bug) |
run-pack | high | verify | Reproduce and repair race conditions, duplicate work or transaction anomalies with data-integrity evidence and safe migration handling. |
| P1 | Post-Upgrade Regression Repair (upgrade-regression-repair) |
guided | moderate | verify | Compare pre/post-upgrade behavior, isolate the compatibility break and repair it without reverting unrelated security or maintenance improvements. |
Code Quality
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Repository Cleanup and Hygiene (repository-cleanup) |
guided | moderate | verify | Remove dead files, stale scripts, generated artifacts and unused dependencies while preserving behavior and repository history. |
| P1 | Decompose an Oversized Module (large-module-decomposition) |
run-pack | moderate | verify | Split a large module along real responsibilities while preserving public behavior and avoiding speculative abstraction. |
| P1 | Reduce Harmful Duplication (duplication-reduction) |
guided | moderate | verify | Identify duplicated logic with meaningful maintenance cost and consolidate it without creating an over-generalized abstraction. |
| P0 | Harden Error Handling (error-handling-hardening) |
guided | moderate | verify | Improve error classification, propagation, user feedback and safe logging across a selected flow. |
| P1 | Improve Type Safety (type-safety-improvement) |
guided | moderate | verify | Replace unsafe casts, implicit any-like behavior and unchecked external data with validated, maintainable types. |
| P1 | Centralize Configuration Safely (configuration-centralization) |
guided | moderate | verify | Consolidate duplicated and hardcoded configuration with typed validation, clear defaults and environment separation. |
| P1 | Improve Operational Logging (logging-improvement) |
guided | moderate | verify | Add structured, actionable and privacy-safe logs around critical operations without noisy duplication. |
| P2 | Targeted Performance Refactor (performance-refactor) |
run-pack | high | verify | Implement a measured performance improvement for one confirmed bottleneck and prove the before/after result. |
Testing
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Establish Unit Test Foundation (unit-test-foundation) |
run-pack | moderate | verify | Introduce a maintainable unit-test baseline around core domain behavior without over-mocking implementation details. |
| P1 | Establish Integration Test Foundation (integration-test-foundation) |
run-pack | moderate | verify | Add real integration tests for persistence or service boundaries using isolated, reproducible dependencies. |
| P0 | Add Playwright Critical-Flow Tests (playwright-critical-flows) |
run-pack | moderate | verify | Cover selected end-to-end user journeys with resilient selectors, deterministic setup and useful failure artifacts. |
| P1 | Build a Focused Regression Suite (regression-suite) |
run-pack | moderate | verify | Turn historically costly defects and critical behaviors into a prioritized regression suite. |
| P1 | Improve Test Isolation (test-isolation) |
guided | moderate | verify | Remove order dependence, shared state and environment leakage while preserving realistic integration behavior. |
| P2 | Speed Up Test Execution (test-performance) |
guided | moderate | verify | Measure test-suite bottlenecks and improve execution time without reducing meaningful coverage or hiding slow failures. |
| P1 | Add API or Integration Contract Tests (contract-tests) |
run-pack | moderate | verify | Protect external and internal service contracts with schema, compatibility and error-behavior tests. |
| P2 | Refactor Test Fixtures and Builders (test-fixture-cleanup) |
guided | low | verify | Replace duplicated or opaque fixtures with clear builders and data ownership while preserving test intent. |
Feature Implementation
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Implement a Feature from a Functional Specification (feature-from-spec) |
run-pack | moderate | repair | Translate a bounded specification into architecture-aware code, tests, documentation and verified user behavior. |
| P1 | Implement a Production-Ready CRUD Module (crud-module) |
run-pack | moderate | repair | Add a complete create/read/update/delete workflow with validation, authorization, persistence, errors and tests. |
| P0 | Add a Compatible API Endpoint (api-endpoint) |
guided | moderate | verify | Implement a new endpoint with validated input, authorization, stable errors, documentation and contract tests. |
| P1 | Add a Reliable Background Job (background-job) |
run-pack | high | repair | Implement idempotent queued work with progress, retries, leases, failure visibility and operational controls. |
| P1 | Add Safe Import and Export (import-export) |
run-pack | high | repair | Implement schema-validated portable import/export with integrity checks, size limits and path safety. |
| P0 | Add Search and Faceted Filtering (search-filter) |
guided | moderate | verify | Implement useful query, filter, sorting, URL state and no-results behavior over an existing dataset. |
| P2 | Implement Roles and Permissions (role-permissions) |
run-pack | high | repair | Add explicit authorization rules, server-side enforcement, admin UX and cross-tenant tests. |
| P1 | Implement an External Service Connector (connector-integration) |
run-pack | high | repair | Add a capability-detected, secret-safe connector with health, degraded states and bounded data synchronization. |
Git Gitea
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Gitea Repository Best-Practices Audit (gitea-best-practices) |
guided | moderate | diagnose | Review repository metadata, branch/tag protection, templates, Actions, release flow and permissions using available evidence. |
| P0 | Design Branch Protection Rules (branch-protection-plan) |
guided | moderate | plan | Produce a repository-appropriate branch protection plan covering pushes, merges, reviews, status checks and exceptions. |
| P1 | Create Issue Template System (issue-template-system) |
guided | low | verify | Design and implement useful bug, feature and operational issue templates with labels and triage guidance. |
| P0 | Create Pull Request Template and Review Checklist (pull-request-template) |
quick | low | verify | Add a concise pull-request template aligned with repository validation, risk and documentation needs. |
| P1 | Design Gitea Release Process (release-process) |
run-pack | moderate | plan | Create a repeatable versioning, tagging, changelog, artifact and rollback workflow suitable for the repository. |
| P1 | Gitea Actions Workflow Audit (actions-workflow-audit) |
guided | high | diagnose | Review workflows, triggers, permissions, secrets, caching and release behavior for correctness and security. |
| P0 | Audit and Repair .gitignore Hygiene (gitignore-hygiene) |
guided | moderate | verify | Identify tracked runtime/generated files and improve ignore rules without hiding required source or configuration examples. |
| P2 | Improve Repository Metadata and Discoverability (repository-metadata) |
guided | low | verify | Align description, topics, README, license, contribution and release metadata for clear internal or public use. |
Release Operations
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Prepare a Release Candidate (release-candidate-prep) |
run-pack | high | repair | Execute a bounded release-readiness pass covering versions, migrations, tests, artifacts, documentation and known limitations. |
| P0 | Clean-Room Installation Validation (clean-room-validation) |
run-pack | moderate | verify | Prove that a fresh clone or deployment can be installed, configured and exercised using only documented steps. |
| P1 | Database Migration Readiness (migration-readiness) |
run-pack | critical | plan | Review and validate pending migrations, compatibility, backup, rollback and deployment sequencing. |
| P0 | Backup and Restore Validation (backup-restore-validation) |
run-pack | high | verify | Test that application data, artifacts, configuration and encryption-key dependencies can be backed up and restored. |
| P1 | Harden and Optimize Docker Images (docker-image-hardening) |
guided | high | verify | Reduce image risk and size while preserving runtime behavior, non-root operation and health checks. |
| P0 | Implement Health and Readiness Checks (health-readiness) |
guided | moderate | verify | Add accurate liveness, readiness and dependency health without hiding partial outages. |
| P1 | Create Release Rollback Plan (rollback-plan) |
guided | high | plan | Document and validate rollback boundaries for application, configuration, database and artifacts. |
| P0 | Generate Evidence-Based Release Notes (release-notes) |
quick | low | plan | Create concise release notes from verified changes, migrations, fixes, known limitations and operator actions. |
Security Reliability
| Priority | Playbook | Type | Risk | Default | Outcome |
|---|---|---|---|---|---|
| P0 | Security Hygiene Audit (security-hygiene-audit) |
run-pack | high | diagnose | Review authentication, authorization, secrets, input validation, dependency risk and unsafe defaults within a defined application scope. |
| P0 | Secrets Exposure Audit (secrets-exposure-audit) |
guided | critical | diagnose | Inspect repository and runtime configuration patterns for committed, logged or exported secrets without echoing sensitive values. |
| P1 | Authorization Boundary Review (authorization-review) |
run-pack | high | diagnose | Trace protected resources and operations to verify server-side enforcement and cross-user or cross-workspace isolation. |
| P1 | Create Application Threat Model (threat-model) |
run-pack | moderate | plan | Identify assets, trust boundaries, abuse cases and prioritized controls tied to the actual architecture. |
| P1 | Failure and Resilience Review (resilience-failure-review) |
run-pack | high | diagnose | Assess dependency outages, retry behavior, idempotency, data loss, degraded states and recovery visibility. |
| P2 | Privacy and Data Handling Review (privacy-data-review) |
run-pack | high | diagnose | Map personal or sensitive data, retention, exports, logging and deletion behavior to identify unnecessary collection and leakage risks. |
Fully authored example packages
repository-health-auditroot-cause-bugfixrepository-cleanupgitea-best-practicesfeature-from-specproduction-readiness-audit
These six packages are duplicated under examples/playbooks/ as normative patterns. They are also part of the 28-package P0 runtime catalog. The other 22 P0 packages are complete publishable packages; P1 and P2 remain governed backlog and must not appear as executable content until promoted through document 36.