Workflow Cookbook / Workflow Operations Kit

Language: English | 日本語 | 简体中文

Workflow Cookbook is a docs and runtime kit for workflow operations and context engineering. It bundles Birdseye/Codemap, Task Seeds, acceptance operations, reusable CI, plugin-based Evidence tracking, and a repo-agnostic adaptive improvement loop blueprint for downstream software.

Recommended read order:

1. docs/birdseye/index.json for the lightweight node graph
2. docs/birdseye/caps/<path>.json for focused point reads

Focus procedure:

• Find node IDs for recently changed files within +/-2 hops from index.json
• Read only the matching caps/*.json files

What's Included

• Birdseye / Codemap for Markdown hub synchronization and dependency mapping
• Operational docs centered on BLUEPRINT, RUNBOOK, EVALUATION, and CHECKLISTS
• LLM behavior tracking through StructuredLogger plugins
• Sample config and consumer sample for the agent-protocols Evidence contract
• A workflow host that can connect agent-taskstate and memx-resolver as optional plugins
• An optional, downstream-facing adaptive improvement loop blueprint for post-release reflection, recall, skill evolution, and reviewed user/workspace models
• Reusable CI / governance workflows and validation scripts

Quick Start

1. Read the core docs: BLUEPRINT.md, RUNBOOK.md, EVALUATION.md

2. Refresh Birdseye:

   python tools/codemap/update.py --since --emit index+caps

3. Record an acceptance result: docs/acceptance/README.md, docs/acceptance/ACCEPTANCE_TEMPLATE.md

4. Review the test quality baseline: docs/addenda/J_Test_Engineering.md

5. Check collected metrics against KPI thresholds: tools/ci/check_metrics_thresholds.py, governance/metrics_thresholds.yaml

6. Validate Birdseye freshness: tools/ci/check_birdseye_freshness.py

7. Try Evidence tracking: tools/protocols/README.md, examples/inference_plugins.agent_protocol.sample.json

8. Try cross-repo plugins: tools/workflow_plugins/README.md, examples/workflow_plugins.cross_repo.sample.json

9. Validate plugin config: tools/workflow_plugins/validate_workflow_plugin_config.py

Navigation

• Start here: BLUEPRINT.md, RUNBOOK.md, EVALUATION.md
• Birdseye / Codemap: docs/BIRDSEYE.md, tools/codemap/README.md, HUB.codex.md
• CI / Governance: CHECKLISTS.md, docs/ci-config.md, docs/ci_phased_rollout_requirements.md
• Quality baseline: docs/addenda/J_Test_Engineering.md, docs/acceptance/README.md, governance/metrics_thresholds.yaml

Skills

• Evidence integration skill: skills/workflow-agent-evidence/SKILL.md
• Agent metadata: skills/workflow-agent-evidence/agents/openai.yaml, skills/workflow-agent-evidence/agents/claude.yaml
• Skill references: skills/workflow-agent-evidence/references/workflow-cookbook.md, skills/workflow-agent-evidence/references/agent-protocols.md
• Protocol plugin guide: tools/protocols/README.md

Common Entry Points

Birdseye / Codemap

python tools/codemap/update.py --since --emit index+caps
python tools/codemap/update.py --since --radius 1 --emit caps
python tools/codemap/update.py --targets docs/birdseye/index.json,docs/birdseye/hot.json --emit index+caps
python tools/ci/check_birdseye_freshness.py --check

Metrics Thresholds

python -m tools.perf.collect_metrics --suite qa --metrics-url <url> --log-path <path>
python tools/ci/check_metrics_thresholds.py --check --metrics-json .ga/qa-metrics.json

LLM Evidence Tracking

• Plugin API: tools/protocols/README.md
• Sample config: examples/inference_plugins.agent_protocol.sample.json
• Consumer sample: examples/agent_protocol_evidence_consumer.sample.py

Task Operations

• Task Seed sample: examples/TASK.sample.md
• Operating constraints: GUARDRAILS.md, RUNBOOK.md
• Release-side docs: CHECKLISTS.md, CHANGELOG.md, docs/acceptance/README.md

Advanced: Cross-Repo Plugins

• Host / config: tools/workflow_plugins/README.md, examples/workflow_plugins.cross_repo.sample.json, schemas/workflow-plugin-config.schema.json
• Config validation: tools/workflow_plugins/validate_workflow_plugin_config.py
• Dispatcher / interfaces: tools/workflow_plugins/runtime.py, tools/workflow_plugins/interfaces.py
• Task / acceptance sync: tools/ci/check_task_acceptance_sync.py, tools/ci/generate_acceptance_index.py
• Docs resolve / ack / stale: tools/context/workflow_docs.py

Reusable CI

• Python CI: .github/workflows/reusable/python-ci.yml
• Security CI: .github/workflows/reusable/security-ci.yml
• Security posture: .github/workflows/security.yml, tools/ci/check_security_posture.py
• Release evidence: .github/workflows/release-evidence.yml, tools/ci/check_release_evidence.py
• Cross-repo integration: .github/workflows/cross-repo-integration.yml
• Governance gate: .github/workflows/governance-gate.yml

See docs/ci-config.md for downstream usage and required job semantics. Use tools/ci/check_ci_gate_matrix.py to validate gate alignment in this repo.

Supporting Docs

• Requirements / spec / design: docs/requirements.md, docs/spec.md, docs/design.md
• Operational addenda: docs/ROADMAP_AND_SPECS.md, docs/addenda/J_Test_Engineering.md, docs/addenda/O_Adaptive_Improvement_Loop.md, docs/addenda/N_Improvement_Backlog.md, docs/addenda/P_Expansion_Candidates.md, docs/addenda/M_Versioning_Release.md
• Security: docs/security/SAC.md, docs/security/Security_Review_Checklist.md

License

MIT. Unless noted otherwise, files copied from this repo into other projects remain under the MIT License.