From aa411d87dfcc36dec7ff5dc2a5a4af5ec23d3000 Mon Sep 17 00:00:00 2001 From: Mike Lekar Date: Sun, 21 Jun 2026 03:59:14 +0300 Subject: [PATCH 1/3] feat: Add AI-assisted setup path for complex repos (setup.sh --ai) Adds an AI-installer skill that enables intelligent, complexity-aware setup for existing repositories. Users run setup.sh --ai to bootstrap workspace infrastructure and invoke the AI skill which scans repo structure, classifies complexity (Zero/Simple/Multi/Complex), proposes configuration proportional to detected needs, previews as unified diffs, and writes after approval. Key capabilities: - Workspace bootstrapping (dirs, skills, workflows, AGENTS.md inference) - 4 runtime adapters (Claude, Cursor, Cline, Antigravity) - --target for running against external repos - --auto for unattended execution (requires explicit --runtime) - Non-destructive: never modifies user files, companion file pattern - Framework coexistence (defers persona routing when BMAD detected) - Clean uninstall via setup.sh --remove (manifest-tracked) - Test infrastructure: shell + Python tests, 4 UJ-based fixtures Planned using BMad Method. Planning artifacts in _bmad-output/. Co-Authored-By: Claude Opus 4.6 (1M context) --- .agents/skills/agentic-os-setup/SKILL.md | 477 ++++++++++++ .../agentic-os-setup/adapters/antigravity.md | 148 ++++ .../agentic-os-setup/adapters/claude.md | 86 +++ .../skills/agentic-os-setup/adapters/cline.md | 85 +++ .../agentic-os-setup/adapters/cursor.md | 138 ++++ .../agentic-os-setup/agents/openai.yaml | 5 + .agents/skills/agentic-os-setup/catalog.md | 213 ++++++ .../examples/complex-output.md | 150 ++++ .../examples/simple-output.md | 65 ++ .../templates/cross-reference.md | 61 ++ .../templates/naming-enforcement.md | 67 ++ .../templates/persona-routing.md | 66 ++ .../templates/quality-gates.md | 72 ++ .../templates/scope-isolation.md | 64 ++ .gitignore | 3 + CLAUDE.md | 5 + CONTRIBUTING.md | 215 ++++++ README.md | 70 +- .../.decision-log.md | 46 ++ .../addendum.md | 141 ++++ .../architecture.md | 686 +++++++++++++++++ .../prd-ai-assisted-setup-2026-06-20/epics.md | 705 ++++++++++++++++++ .../implementation-readiness-report.md | 251 +++++++ .../prd-ai-assisted-setup-2026-06-20/prd.md | 541 ++++++++++++++ .../pull-request.md | 175 +++++ .../.agents/skills/README.md | 35 + .../.agents/skills/agentic-os-setup/SKILL.md | 380 ++++++++++ .../agentic-os-setup/adapters/antigravity.md | 148 ++++ .../agentic-os-setup/adapters/claude.md | 86 +++ .../skills/agentic-os-setup/adapters/cline.md | 85 +++ .../agentic-os-setup/adapters/cursor.md | 138 ++++ .../agentic-os-setup/agents/openai.yaml | 5 + .../skills/agentic-os-setup/catalog.md | 213 ++++++ .../examples/complex-output.md | 150 ++++ .../examples/simple-output.md | 65 ++ .../templates/cross-reference.md | 61 ++ .../templates/naming-enforcement.md | 67 ++ .../templates/persona-routing.md | 66 ++ .../templates/quality-gates.md | 72 ++ .../templates/scope-isolation.md | 64 ++ .../skills/assumption-mapping/SKILL.md | 65 ++ .../assumption-mapping/agents/openai.yaml | 5 + .../skills/assumption-prioritization/SKILL.md | 66 ++ .../agents/openai.yaml | 5 + .../skills/atlassian-jira-sync/SKILL.md | 98 +++ .../atlassian-jira-sync/agents/openai.yaml | 5 + .../.agents/skills/backend-design/SKILL.md | 96 +++ .../skills/backend-design/agents/openai.yaml | 5 + .../.agents/skills/brainstorming/SKILL.md | 60 ++ .../skills/brainstorming/agents/openai.yaml | 5 + .../SKILL.md | 34 + .../agents/openai.yaml | 5 + .../skills/competitor-analysis/SKILL.md | 76 ++ .../competitor-analysis/agents/openai.yaml | 5 + .../.agents/skills/crux-diagnosis/SKILL.md | 71 ++ .../skills/crux-diagnosis/agents/openai.yaml | 5 + .../.agents/skills/davci/SKILL.md | 83 +++ .../.agents/skills/davci/agents/openai.yaml | 5 + .../.agents/skills/decision-journal/SKILL.md | 63 ++ .../decision-journal/agents/openai.yaml | 5 + .../skills/decision-reversibility/SKILL.md | 58 ++ .../decision-reversibility/agents/openai.yaml | 5 + .../skills/difficult-conversations/SKILL.md | 81 ++ .../agents/openai.yaml | 5 + .../skills/executive-update-review/SKILL.md | 47 ++ .../agents/openai.yaml | 5 + .../.agents/skills/experiment-design/SKILL.md | 62 ++ .../experiment-design/agents/openai.yaml | 5 + .../.agents/skills/frontend-design/SKILL.md | 91 +++ .../skills/frontend-design/agents/openai.yaml | 5 + .../google-calendar-schedule-check/SKILL.md | 79 ++ .../agents/openai.yaml | 5 + .../skills/granola-meeting-sync/SKILL.md | 79 ++ .../granola-meeting-sync/agents/openai.yaml | 5 + .../.agents/skills/hidden-agendas/SKILL.md | 71 ++ .../skills/hidden-agendas/agents/openai.yaml | 5 + .../.agents/skills/hypothesis-design/SKILL.md | 62 ++ .../hypothesis-design/agents/openai.yaml | 5 + .../.agents/skills/ideas-summary/SKILL.md | 65 ++ .../skills/ideas-summary/agents/openai.yaml | 5 + .../skills/influence-strategies/SKILL.md | 56 ++ .../influence-strategies/agents/openai.yaml | 5 + .../.agents/skills/interview-cleanup/SKILL.md | 43 ++ .../interview-cleanup/agents/openai.yaml | 5 + .../.agents/skills/jtbd-clustering/SKILL.md | 45 ++ .../skills/jtbd-clustering/agents/openai.yaml | 5 + .../.agents/skills/jtbd-extraction/SKILL.md | 57 ++ .../skills/jtbd-extraction/agents/openai.yaml | 5 + .../skills/limit-based-strategy/SKILL.md | 51 ++ .../limit-based-strategy/agents/openai.yaml | 5 + .../.agents/skills/linear-issue-sync/SKILL.md | 84 +++ .../linear-issue-sync/agents/openai.yaml | 5 + .../skills/llm-coding-guardrails/SKILL.md | 76 ++ .../llm-coding-guardrails/agents/openai.yaml | 5 + .../.agents/skills/mece-analysis/SKILL.md | 64 ++ .../skills/mece-analysis/agents/openai.yaml | 5 + .../skills/meeting-power-dynamics/SKILL.md | 36 + .../meeting-power-dynamics/agents/openai.yaml | 5 + .../skills/message-framing-comms/SKILL.md | 47 ++ .../message-framing-comms/agents/openai.yaml | 5 + .../skills/opportunity-solution-tree/SKILL.md | 87 +++ .../agents/openai.yaml | 5 + .../.agents/skills/ost-intake/SKILL.md | 40 + .../skills/ost-intake/agents/openai.yaml | 5 + .../skills/ost-target-selection/SKILL.md | 47 ++ .../ost-target-selection/agents/openai.yaml | 5 + .../.agents/skills/power-map/SKILL.md | 80 ++ .../skills/power-map/agents/openai.yaml | 5 + .../.agents/skills/prd-writing/SKILL.md | 120 +++ .../skills/prd-writing/agents/openai.yaml | 5 + .../skills/problem-structuring/SKILL.md | 61 ++ .../problem-structuring/agents/openai.yaml | 5 + .../skills/root-cause-analysis/SKILL.md | 55 ++ .../root-cause-analysis/agents/openai.yaml | 5 + .../skills/signal-identification/SKILL.md | 66 ++ .../signal-identification/agents/openai.yaml | 5 + .../skills/slack-message-check/SKILL.md | 75 ++ .../slack-message-check/agents/openai.yaml | 5 + .../.agents/skills/spec-writing/SKILL.md | 93 +++ .../skills/spec-writing/agents/openai.yaml | 5 + .../skills/stakeholder-risk-review/SKILL.md | 47 ++ .../agents/openai.yaml | 5 + .../structured-product-strategy/SKILL.md | 54 ++ .../agents/openai.yaml | 5 + .../skills/systematic-debugging/SKILL.md | 115 +++ .../systematic-debugging/agents/openai.yaml | 5 + .../.agents/skills/tdd/SKILL.md | 105 +++ .../.agents/skills/tdd/agents/openai.yaml | 5 + .../skills/value-chain-mapping/SKILL.md | 38 + .../value-chain-mapping/agents/openai.yaml | 5 + .../.agents/skills/verification/SKILL.md | 92 +++ .../skills/verification/agents/openai.yaml | 5 + .../.agents/skills/writing-plans/SKILL.md | 95 +++ .../skills/writing-plans/agents/openai.yaml | 5 + .../.cursor/rules/002-dates.mdc | 10 + .../.cursor/rules/003-eslint.mdc | 11 + .../.cursor/rules/005-api.mdc | 11 + examples/uj-1-node-monorepo/.gitignore | 48 ++ examples/uj-1-node-monorepo/CLAUDE.md | 6 + .../uj-1-node-monorepo/Workflows/README.md | 58 ++ .../assumption-validation-pipeline.md | 26 + .../Workflows/backlog-processing.md | 91 +++ .../Workflows/core-strategy-development.md | 29 + .../Workflows/daily-standup.md | 61 ++ .../Workflows/decision-quality-pipeline.md | 31 + .../Workflows/meeting-prep-and-recap.md | 29 + .../Workflows/opportunity-mapping-pipeline.md | 23 + .../Workflows/research-to-feature-pipeline.md | 34 + .../Workflows/stakeholder-politics-copilot.md | 29 + .../Workflows/weekly-review.md | 129 ++++ .../Workflows/wrap-up-protocol.md | 76 ++ examples/uj-1-node-monorepo/skills | 1 + .../.cursor/rules/800-core.mdc | 10 + .../.cursor/rules/801-designs.mdc | 10 + .../.cursor/rules/802-operations.mdc | 10 + .../.cursor/rules/803-workitems.mdc | 10 + .../.cursor/rules/804-infra.mdc | 10 + .../.cursor/rules/805-placeholder.mdc | 7 + .../.cursor/rules/806-placeholder.mdc | 7 + .../.cursor/rules/807-placeholder.mdc | 7 + .../.cursor/rules/808-placeholder.mdc | 7 + .../.cursor/rules/809-placeholder.mdc | 7 + examples/uj-2-architect-monorepo/AGENTS.md | 10 + .../.agents/skills/README.md | 35 + .../.agents/skills/agentic-os-setup/SKILL.md | 380 ++++++++++ .../agentic-os-setup/adapters/antigravity.md | 148 ++++ .../agentic-os-setup/adapters/claude.md | 86 +++ .../skills/agentic-os-setup/adapters/cline.md | 85 +++ .../agentic-os-setup/adapters/cursor.md | 138 ++++ .../agentic-os-setup/agents/openai.yaml | 5 + .../skills/agentic-os-setup/catalog.md | 213 ++++++ .../examples/complex-output.md | 150 ++++ .../examples/simple-output.md | 65 ++ .../templates/cross-reference.md | 61 ++ .../templates/naming-enforcement.md | 67 ++ .../templates/persona-routing.md | 66 ++ .../templates/quality-gates.md | 72 ++ .../templates/scope-isolation.md | 64 ++ .../skills/assumption-mapping/SKILL.md | 65 ++ .../assumption-mapping/agents/openai.yaml | 5 + .../skills/assumption-prioritization/SKILL.md | 66 ++ .../agents/openai.yaml | 5 + .../skills/atlassian-jira-sync/SKILL.md | 98 +++ .../atlassian-jira-sync/agents/openai.yaml | 5 + .../.agents/skills/backend-design/SKILL.md | 96 +++ .../skills/backend-design/agents/openai.yaml | 5 + .../.agents/skills/brainstorming/SKILL.md | 60 ++ .../skills/brainstorming/agents/openai.yaml | 5 + .../SKILL.md | 34 + .../agents/openai.yaml | 5 + .../skills/competitor-analysis/SKILL.md | 76 ++ .../competitor-analysis/agents/openai.yaml | 5 + .../.agents/skills/crux-diagnosis/SKILL.md | 71 ++ .../skills/crux-diagnosis/agents/openai.yaml | 5 + .../.agents/skills/davci/SKILL.md | 83 +++ .../.agents/skills/davci/agents/openai.yaml | 5 + .../.agents/skills/decision-journal/SKILL.md | 63 ++ .../decision-journal/agents/openai.yaml | 5 + .../skills/decision-reversibility/SKILL.md | 58 ++ .../decision-reversibility/agents/openai.yaml | 5 + .../skills/difficult-conversations/SKILL.md | 81 ++ .../agents/openai.yaml | 5 + .../skills/executive-update-review/SKILL.md | 47 ++ .../agents/openai.yaml | 5 + .../.agents/skills/experiment-design/SKILL.md | 62 ++ .../experiment-design/agents/openai.yaml | 5 + .../.agents/skills/frontend-design/SKILL.md | 91 +++ .../skills/frontend-design/agents/openai.yaml | 5 + .../google-calendar-schedule-check/SKILL.md | 79 ++ .../agents/openai.yaml | 5 + .../skills/granola-meeting-sync/SKILL.md | 79 ++ .../granola-meeting-sync/agents/openai.yaml | 5 + .../.agents/skills/hidden-agendas/SKILL.md | 71 ++ .../skills/hidden-agendas/agents/openai.yaml | 5 + .../.agents/skills/hypothesis-design/SKILL.md | 62 ++ .../hypothesis-design/agents/openai.yaml | 5 + .../.agents/skills/ideas-summary/SKILL.md | 65 ++ .../skills/ideas-summary/agents/openai.yaml | 5 + .../skills/influence-strategies/SKILL.md | 56 ++ .../influence-strategies/agents/openai.yaml | 5 + .../.agents/skills/interview-cleanup/SKILL.md | 43 ++ .../interview-cleanup/agents/openai.yaml | 5 + .../.agents/skills/jtbd-clustering/SKILL.md | 45 ++ .../skills/jtbd-clustering/agents/openai.yaml | 5 + .../.agents/skills/jtbd-extraction/SKILL.md | 57 ++ .../skills/jtbd-extraction/agents/openai.yaml | 5 + .../skills/limit-based-strategy/SKILL.md | 51 ++ .../limit-based-strategy/agents/openai.yaml | 5 + .../.agents/skills/linear-issue-sync/SKILL.md | 84 +++ .../linear-issue-sync/agents/openai.yaml | 5 + .../skills/llm-coding-guardrails/SKILL.md | 76 ++ .../llm-coding-guardrails/agents/openai.yaml | 5 + .../.agents/skills/mece-analysis/SKILL.md | 64 ++ .../skills/mece-analysis/agents/openai.yaml | 5 + .../skills/meeting-power-dynamics/SKILL.md | 36 + .../meeting-power-dynamics/agents/openai.yaml | 5 + .../skills/message-framing-comms/SKILL.md | 47 ++ .../message-framing-comms/agents/openai.yaml | 5 + .../skills/opportunity-solution-tree/SKILL.md | 87 +++ .../agents/openai.yaml | 5 + .../.agents/skills/ost-intake/SKILL.md | 40 + .../skills/ost-intake/agents/openai.yaml | 5 + .../skills/ost-target-selection/SKILL.md | 47 ++ .../ost-target-selection/agents/openai.yaml | 5 + .../.agents/skills/power-map/SKILL.md | 80 ++ .../skills/power-map/agents/openai.yaml | 5 + .../.agents/skills/prd-writing/SKILL.md | 120 +++ .../skills/prd-writing/agents/openai.yaml | 5 + .../skills/problem-structuring/SKILL.md | 61 ++ .../problem-structuring/agents/openai.yaml | 5 + .../skills/root-cause-analysis/SKILL.md | 55 ++ .../root-cause-analysis/agents/openai.yaml | 5 + .../skills/signal-identification/SKILL.md | 66 ++ .../signal-identification/agents/openai.yaml | 5 + .../skills/slack-message-check/SKILL.md | 75 ++ .../slack-message-check/agents/openai.yaml | 5 + .../.agents/skills/spec-writing/SKILL.md | 93 +++ .../skills/spec-writing/agents/openai.yaml | 5 + .../skills/stakeholder-risk-review/SKILL.md | 47 ++ .../agents/openai.yaml | 5 + .../structured-product-strategy/SKILL.md | 54 ++ .../agents/openai.yaml | 5 + .../skills/systematic-debugging/SKILL.md | 115 +++ .../systematic-debugging/agents/openai.yaml | 5 + .../.agents/skills/tdd/SKILL.md | 105 +++ .../.agents/skills/tdd/agents/openai.yaml | 5 + .../skills/value-chain-mapping/SKILL.md | 38 + .../value-chain-mapping/agents/openai.yaml | 5 + .../.agents/skills/verification/SKILL.md | 92 +++ .../skills/verification/agents/openai.yaml | 5 + .../.agents/skills/writing-plans/SKILL.md | 95 +++ .../skills/writing-plans/agents/openai.yaml | 5 + examples/uj-3-flask-simple/.gitignore | 48 ++ examples/uj-3-flask-simple/CLAUDE.md | 6 + examples/uj-3-flask-simple/README.md | 16 + .../uj-3-flask-simple/Workflows/README.md | 58 ++ .../assumption-validation-pipeline.md | 26 + .../Workflows/backlog-processing.md | 91 +++ .../Workflows/core-strategy-development.md | 29 + .../Workflows/daily-standup.md | 61 ++ .../Workflows/decision-quality-pipeline.md | 31 + .../Workflows/meeting-prep-and-recap.md | 29 + .../Workflows/opportunity-mapping-pipeline.md | 23 + .../Workflows/research-to-feature-pipeline.md | 34 + .../Workflows/stakeholder-politics-copilot.md | 29 + .../Workflows/weekly-review.md | 129 ++++ .../Workflows/wrap-up-protocol.md | 76 ++ examples/uj-3-flask-simple/requirements.txt | 2 + examples/uj-3-flask-simple/skills | 1 + examples/uj-3-flask-simple/src/app.py | 18 + examples/uj-4-rust-antigravity/AGENTS.md | 9 + examples/uj-4-rust-antigravity/Cargo.toml | 7 + examples/uj-4-rust-antigravity/api/Cargo.toml | 10 + .../uj-4-rust-antigravity/core/Cargo.toml | 7 + .../uj-4-rust-antigravity/shared/Cargo.toml | 7 + pytest.ini | 3 + setup.sh | 413 +++++++++- tests/conftest.py | 40 + tests/test_content.py | 335 +++++++++ tests/test_setup.sh | 246 ++++++ 300 files changed, 17315 insertions(+), 14 deletions(-) create mode 100644 .agents/skills/agentic-os-setup/SKILL.md create mode 100644 .agents/skills/agentic-os-setup/adapters/antigravity.md create mode 100644 .agents/skills/agentic-os-setup/adapters/claude.md create mode 100644 .agents/skills/agentic-os-setup/adapters/cline.md create mode 100644 .agents/skills/agentic-os-setup/adapters/cursor.md create mode 100644 .agents/skills/agentic-os-setup/agents/openai.yaml create mode 100644 .agents/skills/agentic-os-setup/catalog.md create mode 100644 .agents/skills/agentic-os-setup/examples/complex-output.md create mode 100644 .agents/skills/agentic-os-setup/examples/simple-output.md create mode 100644 .agents/skills/agentic-os-setup/templates/cross-reference.md create mode 100644 .agents/skills/agentic-os-setup/templates/naming-enforcement.md create mode 100644 .agents/skills/agentic-os-setup/templates/persona-routing.md create mode 100644 .agents/skills/agentic-os-setup/templates/quality-gates.md create mode 100644 .agents/skills/agentic-os-setup/templates/scope-isolation.md create mode 100644 CONTRIBUTING.md create mode 100644 _bmad-output/prd-ai-assisted-setup-2026-06-20/.decision-log.md create mode 100644 _bmad-output/prd-ai-assisted-setup-2026-06-20/addendum.md create mode 100644 _bmad-output/prd-ai-assisted-setup-2026-06-20/architecture.md create mode 100644 _bmad-output/prd-ai-assisted-setup-2026-06-20/epics.md create mode 100644 _bmad-output/prd-ai-assisted-setup-2026-06-20/implementation-readiness-report.md create mode 100644 _bmad-output/prd-ai-assisted-setup-2026-06-20/prd.md create mode 100644 _bmad-output/prd-ai-assisted-setup-2026-06-20/pull-request.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/README.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/antigravity.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/claude.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/cline.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/cursor.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/catalog.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/examples/complex-output.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/examples/simple-output.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/cross-reference.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/naming-enforcement.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/persona-routing.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/quality-gates.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/scope-isolation.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/assumption-mapping/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/assumption-mapping/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/assumption-prioritization/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/assumption-prioritization/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/atlassian-jira-sync/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/atlassian-jira-sync/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/backend-design/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/backend-design/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/brainstorming/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/brainstorming/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/challenging-stakeholder-questions/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/challenging-stakeholder-questions/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/competitor-analysis/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/competitor-analysis/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/crux-diagnosis/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/crux-diagnosis/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/davci/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/davci/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/decision-journal/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/decision-journal/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/decision-reversibility/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/decision-reversibility/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/difficult-conversations/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/difficult-conversations/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/executive-update-review/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/executive-update-review/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/experiment-design/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/experiment-design/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/frontend-design/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/frontend-design/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/google-calendar-schedule-check/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/google-calendar-schedule-check/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/granola-meeting-sync/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/granola-meeting-sync/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/hidden-agendas/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/hidden-agendas/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/hypothesis-design/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/hypothesis-design/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/ideas-summary/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/ideas-summary/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/influence-strategies/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/influence-strategies/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/interview-cleanup/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/interview-cleanup/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/jtbd-clustering/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/jtbd-clustering/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/jtbd-extraction/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/jtbd-extraction/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/limit-based-strategy/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/limit-based-strategy/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/linear-issue-sync/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/linear-issue-sync/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/llm-coding-guardrails/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/llm-coding-guardrails/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/mece-analysis/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/mece-analysis/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/meeting-power-dynamics/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/meeting-power-dynamics/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/message-framing-comms/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/message-framing-comms/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/opportunity-solution-tree/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/opportunity-solution-tree/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/ost-intake/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/ost-intake/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/ost-target-selection/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/ost-target-selection/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/power-map/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/power-map/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/prd-writing/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/prd-writing/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/problem-structuring/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/problem-structuring/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/root-cause-analysis/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/root-cause-analysis/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/signal-identification/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/signal-identification/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/slack-message-check/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/slack-message-check/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/spec-writing/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/spec-writing/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/stakeholder-risk-review/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/stakeholder-risk-review/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/structured-product-strategy/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/structured-product-strategy/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/systematic-debugging/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/systematic-debugging/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/tdd/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/tdd/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/value-chain-mapping/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/value-chain-mapping/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/verification/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/verification/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.agents/skills/writing-plans/SKILL.md create mode 100644 examples/uj-1-node-monorepo/.agents/skills/writing-plans/agents/openai.yaml create mode 100644 examples/uj-1-node-monorepo/.cursor/rules/002-dates.mdc create mode 100644 examples/uj-1-node-monorepo/.cursor/rules/003-eslint.mdc create mode 100644 examples/uj-1-node-monorepo/.cursor/rules/005-api.mdc create mode 100644 examples/uj-1-node-monorepo/.gitignore create mode 100644 examples/uj-1-node-monorepo/CLAUDE.md create mode 100644 examples/uj-1-node-monorepo/Workflows/README.md create mode 100644 examples/uj-1-node-monorepo/Workflows/assumption-validation-pipeline.md create mode 100644 examples/uj-1-node-monorepo/Workflows/backlog-processing.md create mode 100644 examples/uj-1-node-monorepo/Workflows/core-strategy-development.md create mode 100644 examples/uj-1-node-monorepo/Workflows/daily-standup.md create mode 100644 examples/uj-1-node-monorepo/Workflows/decision-quality-pipeline.md create mode 100644 examples/uj-1-node-monorepo/Workflows/meeting-prep-and-recap.md create mode 100644 examples/uj-1-node-monorepo/Workflows/opportunity-mapping-pipeline.md create mode 100644 examples/uj-1-node-monorepo/Workflows/research-to-feature-pipeline.md create mode 100644 examples/uj-1-node-monorepo/Workflows/stakeholder-politics-copilot.md create mode 100644 examples/uj-1-node-monorepo/Workflows/weekly-review.md create mode 100644 examples/uj-1-node-monorepo/Workflows/wrap-up-protocol.md create mode 120000 examples/uj-1-node-monorepo/skills create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/800-core.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/801-designs.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/802-operations.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/803-workitems.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/804-infra.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/805-placeholder.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/806-placeholder.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/807-placeholder.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/808-placeholder.mdc create mode 100644 examples/uj-2-architect-monorepo/.cursor/rules/809-placeholder.mdc create mode 100644 examples/uj-2-architect-monorepo/AGENTS.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/README.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/antigravity.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/claude.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/cline.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/cursor.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/catalog.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/examples/complex-output.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/examples/simple-output.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/cross-reference.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/naming-enforcement.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/persona-routing.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/quality-gates.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/scope-isolation.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/assumption-mapping/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/assumption-mapping/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/assumption-prioritization/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/assumption-prioritization/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/atlassian-jira-sync/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/atlassian-jira-sync/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/backend-design/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/backend-design/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/brainstorming/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/brainstorming/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/challenging-stakeholder-questions/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/challenging-stakeholder-questions/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/competitor-analysis/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/competitor-analysis/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/crux-diagnosis/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/crux-diagnosis/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/davci/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/davci/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/decision-journal/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/decision-journal/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/decision-reversibility/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/decision-reversibility/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/difficult-conversations/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/difficult-conversations/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/executive-update-review/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/executive-update-review/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/experiment-design/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/experiment-design/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/frontend-design/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/frontend-design/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/google-calendar-schedule-check/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/google-calendar-schedule-check/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/granola-meeting-sync/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/granola-meeting-sync/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/hidden-agendas/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/hidden-agendas/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/hypothesis-design/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/hypothesis-design/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/ideas-summary/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/ideas-summary/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/influence-strategies/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/influence-strategies/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/interview-cleanup/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/interview-cleanup/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/jtbd-clustering/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/jtbd-clustering/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/jtbd-extraction/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/jtbd-extraction/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/limit-based-strategy/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/limit-based-strategy/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/linear-issue-sync/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/linear-issue-sync/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/llm-coding-guardrails/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/llm-coding-guardrails/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/mece-analysis/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/mece-analysis/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/meeting-power-dynamics/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/meeting-power-dynamics/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/message-framing-comms/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/message-framing-comms/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/opportunity-solution-tree/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/opportunity-solution-tree/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/ost-intake/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/ost-intake/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/ost-target-selection/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/ost-target-selection/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/power-map/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/power-map/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/prd-writing/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/prd-writing/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/problem-structuring/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/problem-structuring/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/root-cause-analysis/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/root-cause-analysis/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/signal-identification/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/signal-identification/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/slack-message-check/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/slack-message-check/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/spec-writing/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/spec-writing/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/stakeholder-risk-review/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/stakeholder-risk-review/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/structured-product-strategy/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/structured-product-strategy/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/systematic-debugging/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/systematic-debugging/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/tdd/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/tdd/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/value-chain-mapping/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/value-chain-mapping/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/verification/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/verification/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.agents/skills/writing-plans/SKILL.md create mode 100644 examples/uj-3-flask-simple/.agents/skills/writing-plans/agents/openai.yaml create mode 100644 examples/uj-3-flask-simple/.gitignore create mode 100644 examples/uj-3-flask-simple/CLAUDE.md create mode 100644 examples/uj-3-flask-simple/README.md create mode 100644 examples/uj-3-flask-simple/Workflows/README.md create mode 100644 examples/uj-3-flask-simple/Workflows/assumption-validation-pipeline.md create mode 100644 examples/uj-3-flask-simple/Workflows/backlog-processing.md create mode 100644 examples/uj-3-flask-simple/Workflows/core-strategy-development.md create mode 100644 examples/uj-3-flask-simple/Workflows/daily-standup.md create mode 100644 examples/uj-3-flask-simple/Workflows/decision-quality-pipeline.md create mode 100644 examples/uj-3-flask-simple/Workflows/meeting-prep-and-recap.md create mode 100644 examples/uj-3-flask-simple/Workflows/opportunity-mapping-pipeline.md create mode 100644 examples/uj-3-flask-simple/Workflows/research-to-feature-pipeline.md create mode 100644 examples/uj-3-flask-simple/Workflows/stakeholder-politics-copilot.md create mode 100644 examples/uj-3-flask-simple/Workflows/weekly-review.md create mode 100644 examples/uj-3-flask-simple/Workflows/wrap-up-protocol.md create mode 100644 examples/uj-3-flask-simple/requirements.txt create mode 120000 examples/uj-3-flask-simple/skills create mode 100644 examples/uj-3-flask-simple/src/app.py create mode 100644 examples/uj-4-rust-antigravity/AGENTS.md create mode 100644 examples/uj-4-rust-antigravity/Cargo.toml create mode 100644 examples/uj-4-rust-antigravity/api/Cargo.toml create mode 100644 examples/uj-4-rust-antigravity/core/Cargo.toml create mode 100644 examples/uj-4-rust-antigravity/shared/Cargo.toml create mode 100644 pytest.ini create mode 100644 tests/conftest.py create mode 100644 tests/test_content.py create mode 100755 tests/test_setup.sh diff --git a/.agents/skills/agentic-os-setup/SKILL.md b/.agents/skills/agentic-os-setup/SKILL.md new file mode 100644 index 0000000..73de62c --- /dev/null +++ b/.agents/skills/agentic-os-setup/SKILL.md @@ -0,0 +1,477 @@ +--- +name: agentic-os-setup +description: AI-assisted repo setup — scans structure, classifies complexity, infers GOALS.md, generates runtime-specific configuration. Use when the user says "run agentic-os setup", "set up my repo", or "configure agentic-os". +--- + +# Agentic-OS AI-Assisted Setup + +## Purpose + +Intelligent, complexity-aware setup for agentic-os. Performs two jobs: + +1. **Workspace bootstrapping** — Creates the agentic-os workspace structure (directories, AGENTS.md, GOALS.md, BACKLOG.md, symlinks, skills, workflows) in the target repo, auto-populating GOALS.md from repo analysis instead of a questionnaire. +2. **Configuration generation** — Scans repo structure, classifies complexity, proposes runtime-specific configuration proportional to detected needs, previews as unified diffs, and writes only after approval. + +Both jobs run in sequence. The AI replaces the classic setup questionnaire entirely — it infers what the questionnaire would have asked from the repo's own signals. + +## Mode Detection + +Before beginning, check for the context bridge file at `.agents/.agentic-os-setup-context.json`. If present, read it to determine: +- `runtimes`: which runtime adapters to generate for +- `dry_run`: if true, perform full analysis and proposal but write zero files +- `track`: if true, skip gitignore management (files will be committed) +- `auto`: if true, show the diff preview but skip the approval gate — write immediately after presenting diffs + +Note: By the time you run, `setup.sh` has already bootstrapped the workspace (copied skills, workflows, dirs, BACKLOG.md, symlinks into this repo). Your job is the smart parts: scan, classify, infer GOALS.md, generate runtime config, and handle files that need cross-referencing (CLAUDE.md, AGENTS.md, etc.). + +**Track vs Gitignore decision:** If `track` is not explicitly set in the context bridge (i.e., the user didn't pass `--track`), YOU decide based on repo signals: +- **Gitignore (private):** Personal workspace, solo developer, no team indicators, sensitive content (personal goals, private structure) +- **Track (shared):** Team repo, multiple contributors in git log, existing shared configs (.cursor/rules/, AGENTS.md already tracked), CI/CD present, CONTRIBUTING.md exists + +If you decide to track (not gitignore), skip the gitignore managed block entirely. State your reasoning in the proposal: "These files appear team-relevant and will be tracked in git (not gitignored)." + +If the context bridge file is not present, ask the user which runtimes they want and whether this is a dry run. + +Check for an existing manifest at `.agents/.agentic-os-manifest.json`: +- If manifest exists: this is a **re-run**. Phase 1 does not support re-run — inform the user that re-run with delta merging is planned for Phase 2, and suggest `setup.sh --remove` followed by a fresh `--ai` run if they want to regenerate. +- If no manifest: this is a **first-run**. Proceed with workspace bootstrapping, then scanning. + +## AI Responsibilities (Post-Bootstrap) + +`setup.sh` has already handled the "dumb" copying: directories, BACKLOG.md, Workflows/, .agents/skills/, symlinks, .gitignore template. Your job is the smart inference and generation: + +### 1. Create or update AGENTS.md + +If `AGENTS.md` does NOT exist: generate a **complete** AGENTS.md that combines: + +**A) All standard agentic-os behavioral instructions** (these are NOT optional — they make the AI useful): +- How to Work With Files (read, write, list, search patterns) +- Task File Format (full YAML frontmatter template: title, category, priority, status, dates, resource_refs) +- Priority Levels — MUST use P0/P1/P2/P3 format exactly: + - **P0**: Critical/urgent, must do THIS WEEK (max 3 recommended) + - **P1**: Important, has deadlines, affects others (max 5 recommended) + - **P2**: Normal priority, can be scheduled (default) + - **P3**: Low priority, nice-to-have +- Backlog Processing Workflow (step-by-step: read → gather context → dedup check → clarify → create → summarize) +- Daily Guidance Workflow (read tasks → filter active → read goals → recommend focus → flag blocked) +- Goals Alignment rules (tie tasks to goals, flag orphan tasks) +- Skills Reference table (categorized: planning, building, analysis, research, decisions, strategy, meetings, stakeholders) +- Skill Routing Policy (execution-first: small task → direct edit, medium → plan+tdd, large → prd+plan+tdd) +- Workflows Reference table (prompt → workflow file mapping) +- Helpful Prompts section (examples: "Show my P0 and P1 tasks", "List blocked tasks", "Archive completed tasks", "Create an eval for this session") +- Subagent Delegation patterns (when to use, when not to, delegation order, output contract) +- Verification Discipline (identify → run → verify → only then claim done) +- Interaction Style (direct, batch questions, never delete user content) +- Session Evals (when to create, eval workflow steps) +- Maintenance Tasks — MUST include ALL of these: + - Prune completed tasks (>30 days old → archive) + - Check priority distribution (warn if >3 P0 or >5 P1) + - Update AGENTS.md (when learning something important about user preferences or workflow, suggest adding it here) + - Review evals (weekly, apply learnings) +- Writing Style Guidelines (avoid cliches, be direct and concise) + +**B) Repo-specific customizations** (discovered during scanning): +- **Workspace layout** — the ACTUAL directory structure two levels deep +- **Task categories** — derived from concern domains found (not generic — use #devex-platform, #access-management, etc.) +- **Scope boundaries** — real isolation rules between domains +- **Cross-references** — real linkage rules between related folders +- **Naming standards** — real patterns detected in each domain + +The workspace layout should go **two levels deep** for major directories: +``` +docs/workitems/ — Cross-project work items (ZSP, CI, Crossplane) +docs/workitems/devex/ — DevEx Platform project (130+ items, ADO-synced) +docs/designs/ — Architecture decisions and designs + ├── access-management/ — ZSP AWS access model + ├── github-jira-migration-plan/ + └── ... (11 initiatives) +``` + +**Critical:** The behavioral sections (A) must be COMPLETE — don't summarize them into one-liners. The repo-specific sections (B) replace the generic equivalents from the template. The result should be a full operational manual for the AI, not a summary. + +If `AGENTS.md` already exists: extend it with a managed block containing agentic-os behavioral rules (scope isolation, cross-references, etc.) — same as Antigravity adapter behavior. + +### 2. Create or update AI tool wrapper files + +For each targeted runtime, create the appropriate wrapper file if it doesn't exist: +- **Claude**: `CLAUDE.md` — if missing, create with `@AGENTS.md` and a Skills section pointing to `.agents/skills/`. If exists, create `CLAUDE-agentic-os.md` companion that includes the Skills section. +- **Codex**: `CODEX.md` — if missing, create with reference to AGENTS.md + skill location. +- **Pi**: `PI.md` — if missing, create with reference to AGENTS.md + skill location. +- **OpenClaw**: `OPENCLAW.md` — if missing, create with reference to AGENTS.md + skill location. + +The Claude wrapper (or companion) MUST include a section like: +```markdown +## Skills + +Canonical skills are available at `.agents/skills/*/SKILL.md` (also accessible via `.claude/skills/`). +To run a skill: read its SKILL.md and follow the instructions within. +``` + +This ensures Claude Code knows where skills live even if auto-discovery doesn't surface them. + +### 3. Auto-generate GOALS.md + +Instead of asking a questionnaire, infer goals from repo signals. Use the **deep scanning results** — don't just read top-level, read the actual work being done: + +| Classic Question | AI Inference Source | +|-----------------|-------------------| +| "What's your current role?" | README, CONTRIBUTING, package.json author, git config, folder structure purpose. Also: what kind of work lives here (architecture docs → architect; work items → team lead; hiring → manager) | +| "What's your professional vision?" | Repo scope: what domain it serves, what it's building toward. Look at design docs and POM artifacts for strategic intent. | +| "12-month success criteria?" | Major initiatives in designs/ (each subfolder = a goal). Active epics in work items. Hiring roles = team growth goal. | +| "This quarter objectives?" | Recent commits focus, active branches, work-in-progress items. What's in draft state vs completed. | +| "Top 3 priorities?" | Largest/most-active subfolders. Most-recent work items. Active hiring positions. | +| "Key initiatives?" | Each major design folder, each project-scoped work item subfolder, active hiring rounds — present as a table with status | + +Write `GOALS.md` using the standard template structure. Mark inferred sections with `[AI-inferred — refine as needed]`. Leave unknowable fields empty with ``. + +Include a **Key Initiatives** table that maps the actual work streams found (with file counts and activity indicators). This gives the user immediate visibility into what the AI detected as their active work. + +### 4. Generate runtime-specific configuration + +This is the classification + proposal flow (Scanning → Classification → Proposal → Preview → Write) described in the sections below. + +--- + +## Scanning Protocol + +### What to Read + +Scan the repository filesystem **two levels deep** for structural signals. The goal is to understand not just top-level folders but the project/team/initiative scoping within them: + +**Level 1 — Root directories:** +1. **Top-level directories** — list all directories at root (ignore hidden dirs except `.cursor/`, `.claude/`, `.cline/`) +2. **Config files at root** — package.json, pyproject.toml, Cargo.toml, go.mod, Makefile, docker-compose.yml, terraform/, .github/ +3. **Existing AI configuration** — .cursor/rules/*.mdc, CLAUDE.md, .clinerules, AGENTS.md, .claude/ +4. **Agent frameworks** — _bmad/, .agents/ contents +5. **Documentation** — docs/, README.md, CONTRIBUTING.md +6. **Team indicators** — directories containing "team", group-based folder structures + +**Level 2 — Subdirectory structure (critical for complexity detection):** +7. **Scan one level inside each major directory** (docs/, src/, packages/, etc.) to identify: + - **Project/team scoping** — subdirectories that represent distinct projects, teams, or initiatives (e.g., `docs/workitems/devex/` is a project-scoped collection, not just "workitems") + - **Initiative groupings** — design folders that each represent a major work stream (e.g., `docs/designs/access-management/`, `docs/designs/github-jira-migration-plan/`) + - **Role-based folders** — hiring/interview folders scoped by position (e.g., `docs/JoBInterviews/2026-PlatformEng/`) + - **File count per subfolder** — a folder with 130 files is a major concern; a folder with 3 is a leaf + +8. **Identify the real concern domains** — don't just map top-level directories. Understand what WORK is being done: + - If `docs/workitems/devex/` has 130 items and `docs/workitems/` root has 15, then "DevEx Platform" is the primary project, not just "workitems" + - If `docs/designs/` has 11 subdirectories, each is likely a distinct initiative worth naming + - If there are role-specific interview/position folders, hiring is an active concern domain + +9. **Assess initiative scale** — for each concern domain identified: + - Count files to gauge volume + - Note naming patterns (ADO IDs, date prefixes, kebab-case) + - Identify active vs archived (recent dates vs old) + - Look for cross-references between domains (work items referencing designs, interviews referencing positions) + +### What NOT to Read + +- File contents beyond config/manifest files (respect privacy — NFR-5) +- Binary files +- node_modules/, .git/, build artifacts, vendor/ +- Any file > 100KB + +### Signal Matching + +Cross-reference detected patterns against `catalog.md`. For each matched signal, note: +- Which complexity dimension it contributes to +- What setup implications it carries +- Any coexistence behavior required + +## Classification Logic + +Use the **highest-dimension-wins** scoring algorithm: + +### Dimensions + +| Dimension | Zero | Simple | Multi | Complex | +|-----------|------|--------|-------|---------| +| Top-level concern folders | 0 | 1-2 | 3-4 | 5+ | +| Project-scoped subfolders (distinct initiatives/teams within a domain) | 0 | 0 | 1-2 | 3+ | +| Existing AI config files | 0 | 0-1 | 2-3 | 4+ | +| Team/group indicators | 0 | 0 | 1 | 2+ | +| Cross-domain references detected | 0 | 0 | 1 | 2+ | +| Agent framework present (_bmad/, etc.) | No | No | No | Yes | + +### Algorithm + +1. For each dimension, map the detected count to a tier (Zero=0, Simple=1, Multi=2, Complex=3) +2. Take the maximum score across all dimensions +3. If max = 0 → **Zero** tier; 1 → **Simple**; 2 → **Multi**; 3 → **Complex** +4. Present the classification WITH the scoring breakdown so the user can challenge it + +### Override Protocol + +Always propose the classification with rationale. The user can override up or down. Respect the override without argument. + +### Calibration + +- A repo with `_bmad/` is automatically Complex (framework presence is a strong signal) +- A repo with only `src/` and `tests/` should never exceed Simple regardless of file count +- See `examples/simple-output.md` and `examples/complex-output.md` for calibration + +## Proposal Generation + +Based on the classified tier and detected signals, assemble a configuration proposal: + +### Tier Output Expectations + +| Tier | What Gets Generated | +|------|-------------------| +| Zero | Nothing — repo is empty. Suggest running classic `setup.sh` instead. | +| Simple | 1 config file per targeted runtime. Minimal: basic project context, no persona routing. | +| Multi | Config files per runtime + AGENTS.md with persona definitions. Persona routing, scope isolation. | +| Complex | Full output: AGENTS.md, GOALS.md (if none exists), config files with persona routing, scope isolation, cross-reference enforcement, quality gates. | + +### Assembly Process + +1. Select applicable templates from `templates/` based on tier and detected signals (check each template's "When to Use" section) +2. Fill template placeholders with detected values (domains, personas, relationships) +3. Format output per runtime using the corresponding adapter in `adapters/` +4. Collect all proposed files into a unified proposal + +### Relationship Discovery + +- **Manifest-declared relationships** (found in package.json workspaces, go.work, etc.) are trusted — include them directly +- **AI-inferred relationships** (e.g., folder naming patterns suggest linkage) require user confirmation before inclusion in generated rules + +## Framework Coexistence + +When `_bmad/` directory is detected during scanning: +- Do NOT generate persona routing rules (defer persona ownership to BMAD) +- Limit generated rules to: scope isolation, cross-reference enforcement, naming patterns +- Explain what you're deferring and why in the proposal + +When other AI configs exist (.cursor/rules/, CLAUDE.md, .clinerules): +- Do NOT modify or replace them +- Generate agentic-os rules as additive companion files (see adapter specs for pre-existing file behavior) +- Check for glob collisions with existing .cursor/rules/ before proposing new ones + +## Diff Preview Protocol + +All proposed changes MUST be presented as unified diffs before any files are written. + +### New Files + +Present as a diff against `/dev/null`: + +```diff +--- /dev/null ++++ b/CLAUDE.md +@@ -0,0 +1,25 @@ ++# Project Context ++ ++{full file content with + prefix on each line} +``` + +### Extensions to Existing Files + +For files being extended (e.g., AGENTS.md managed block append, .gitignore append): + +```diff +--- a/.gitignore ++++ b/.gitignore +@@ -42,0 +43,5 @@ ++# === AGENTIC-OS GENERATED (do not edit this block) === ++CLAUDE.md ++.agents/.agentic-os-manifest.json ++# === END AGENTIC-OS GENERATED === +``` + +### Presentation Rules + +1. Show ALL proposed files in a single diff block (or clearly labeled separate blocks) +2. Use standard unified diff format compatible with `patch` and `git apply` +3. Include file paths relative to repo root +4. For multi-file proposals, separate each file's diff with a blank line +5. After presenting diffs, clearly state: "These are the proposed changes. Approve all, approve selectively, or reject?" + +### Selective Approval + +The user can: +- **Approve all** — write everything as proposed +- **Approve selectively** — specify which files to write (e.g., "write CLAUDE.md and the manifest but skip the Cursor rules") +- **Reject** — write nothing, end the session + +Respect the user's selection exactly. Only write approved files. + +### Auto-Approval Mode + +When `auto: true` is set in the context bridge: + +1. Present all diffs exactly as in normal mode (for logging/audit) +2. **Do NOT wait for user approval** — proceed directly to writing +3. If conflict detection finds a collision: **FAIL with error** (do not silently overwrite). Print the conflict report and exit without writing any files. +4. If `dry_run` is also true: show diffs, write nothing (dry-run takes precedence over auto) + +Auto mode is designed for unattended execution where the user has pre-selected their runtimes via `--runtime`. It still shows what will be written but doesn't pause for confirmation. + +## Dry-Run Mode + +When dry-run is active (detected from context bridge `dry_run: true` or user states "dry run"): + +1. Execute the FULL workflow: scanning, classification, proposal generation +2. Present diffs exactly as in normal mode +3. **Write ZERO files to disk** +4. Do NOT create a manifest +5. Do NOT modify .gitignore +6. Clearly indicate at the start and end: "DRY RUN — no files will be written" + +The user gets full visibility into what WOULD happen, without any side effects. + +## Conflict Detection Protocol + +Before writing ANY file, perform these safety checks: + +### Cursor Glob Collision Detection + +When proposing `.cursor/rules/` files: + +1. List ALL existing `.mdc` files in `.cursor/rules/` +2. Parse YAML frontmatter of each to extract `globs` value +3. Compare each proposed glob against all existing globs +4. A collision exists if: + - Proposed glob is identical to an existing glob + - Proposed glob is a superset of an existing glob (e.g., `src/**/*` covers `src/components/**/*`) + - Proposed glob overlaps with an existing glob (shared file matches) + +**On collision:** +- Report: existing file name, its glob, proposed glob, and why they conflict +- Propose alternatives: narrower glob that avoids overlap, or skip that rule +- Never write a colliding rule without user approval of the alternative + +### Numbering Respect + +When generating Cursor `.mdc` files: +1. Scan existing files for their numeric prefixes +2. Identify the highest number in use +3. Use the next available number (e.g., if 805 exists, use 806) +4. NEVER renumber or move existing files +5. If no existing rules, default to 900-band + +### Non-Destructive File Policy + +**Core invariant:** Never modify or delete user files. + +**Exceptions (append-only managed blocks):** +- `.gitignore` — append a delimited block at the end (never edit existing lines) +- `AGENTS.md` — append a managed block at the end (never edit existing content above the block) + +**For all other existing files:** +- If the target path already exists and is NOT one of the append-only exceptions: create a companion file instead (see adapter specs for per-runtime behavior) +- If an existing managed block has been edited by the user (hash mismatch): warn and skip overwrite + +### Framework Coexistence Check + +When `_bmad/` is detected: +- Skip persona routing template entirely +- Explain in the proposal: "Persona routing deferred to BMAD framework (detected `_bmad/` directory)" +- Only generate: scope isolation, cross-reference enforcement, naming, quality gates + +## Write Protocol + +After the user approves the proposal (fully or selectively), write files following this exact sequence: + +### Write Sequence + +1. Create approved configuration files (CLAUDE.md, .cursor/rules/*.mdc, .clinerules, AGENTS.md extension) +2. Write the manifest (`.agents/.agentic-os-manifest.json`) +3. Update .gitignore (unless `--track` was specified) + +### Manifest Schema + +Write to `.agents/.agentic-os-manifest.json`: + +```json +{ + "version": "1.0.0", + "created_at": "", + "complexity_tier": "", + "runtimes_targeted": ["", ""], + "files": [ + { + "path": "", + "created_at": "", + "content_hash": "sha256:" + } + ], + "denied_relationships": [], + "detected_frameworks": [""] +} +``` + +**Field definitions:** +- `version` — Schema version (always "1.0.0" for Phase 1). Future phases add fields but never remove or rename existing ones (additive-only evolution). +- `created_at` — When the setup was run +- `complexity_tier` — The classified tier +- `runtimes_targeted` — Which runtimes were configured +- `files` — Every file created or modified by this run. Each entry has the file path, creation timestamp, and SHA-256 hash of content. +- `denied_relationships` — Relationships the user rejected during proposal (prevents re-proposal on future re-runs) +- `detected_frameworks` — Frameworks found during scanning (e.g., "bmad") + +**Important:** The manifest must include ALL generated files — this is what `setup.sh --remove` uses for clean uninstall. Missing entries = orphaned files on removal. + +### Gitignore Management + +**Default behavior** (when `--track` was NOT specified): + +Append a managed block at the end of `.gitignore`: + +```gitignore +# === AGENTIC-OS GENERATED (do not edit this block) === + +.agents/.agentic-os-manifest.json +# === END AGENTIC-OS GENERATED === +``` + +Rules: +- List every file path from the manifest's `files` array +- Include the manifest itself +- Always append at the end — never insert or modify existing gitignore content +- If `.gitignore` doesn't exist, create it with just the managed block +- The context bridge file (`.agents/.agentic-os-setup-context.json`) is NOT gitignored — it's ephemeral and deleted by `--remove` + +**When `--track` is specified (explicit flag OR AI-inferred):** +- Do NOT modify `.gitignore` +- Generated files will be committed to the repository +- This is intentional — the configuration is shared with the team + +**AI-inferred track decision** (when `track` is `false` in context bridge and user didn't explicitly pass `--track`): + +Decide based on repo signals: +- **Gitignore** if: solo dev, personal workspace, no team indicators, sensitive/personal content +- **Track** if: team repo (multiple git authors), existing tracked AI configs (.cursor/rules/ committed), CONTRIBUTING.md present, CI/CD workflows exist, shared AGENTS.md already tracked + +State the decision in the proposal. If you infer "track", explain why: "This appears to be a team repo (3 contributors, shared .cursor/rules/) — generated files will be tracked, not gitignored." + +### Managed Block Specification + +For files that use managed blocks (AGENTS.md, .gitignore): + +**HTML-comment style** (for AGENTS.md and other markdown files): +``` + +{content} + +``` + +**Comment style** (for .gitignore and other non-markdown files): +``` +# === AGENTIC-OS GENERATED (do not edit this block) === +{content} +# === END AGENTIC-OS GENERATED === +``` + +**Hash computation:** +- Hash the content BETWEEN the markers (not including markers themselves) +- Use SHA-256 +- Store as hex string in the start marker +- Purpose: Phase 2 re-run can detect if user manually edited managed content + +### Post-Write Confirmation + +After writing all approved files: +1. Print a summary of what was written (file paths and sizes) +2. Confirm the manifest was created +3. Confirm gitignore status (updated or skipped due to --track) +4. Remind user: "To undo, run: setup.sh --remove" diff --git a/.agents/skills/agentic-os-setup/adapters/antigravity.md b/.agents/skills/agentic-os-setup/adapters/antigravity.md new file mode 100644 index 0000000..408abfc --- /dev/null +++ b/.agents/skills/agentic-os-setup/adapters/antigravity.md @@ -0,0 +1,148 @@ +# Adapter: Antigravity + +## Purpose + +Describes how to format agentic-os generated output for Antigravity AI consumption via AGENTS.md. + +## File Path Convention + +- **Primary:** `AGENTS.md` at repo root +- **Behavior:** Always EXTEND existing content — never replace + +## Format Specification + +Antigravity reads AGENTS.md as its primary instruction file. It expects structured markdown with: + +- `##` headers for major sections (Personas, Rules, Standards) +- `###` headers for subsections (individual personas, rule groups) +- Tables for structured data (scope boundaries, relationships) +- Bullet lists for behavioral rules +- Imperative tone ("Focus on X", "Validate Y", "Never Z") + +## Constraints + +- Single file (AGENTS.md) +- Must coexist with user-written content +- Agentic-os content lives ONLY within managed block markers +- User content above the managed block is never touched +- If no AGENTS.md exists, create one entirely within managed markers + +## Managed Block Format + +```markdown + +{generated content goes here} + +``` + +- **Start marker:** `` +- **End marker:** `` +- **Hash:** SHA-256 of the content between markers (enables future re-run detection) +- **Placement:** Always at the END of AGENTS.md (below any user content) + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No AGENTS.md exists | Create AGENTS.md with content entirely within managed block | +| AGENTS.md exists without managed block | Append managed block at end of file | +| AGENTS.md exists with managed block | Replace managed block content (preserve everything outside) | +| User edited content inside managed block | Detect hash mismatch → warn user and skip overwrite | + +## Extend Semantics + +``` +AGENTS.md structure: +┌─────────────────────────────────────────────────────────────────┐ +│ [User's original content] │ ← never touched +│ ... │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ## Agentic-OS Generated Rules │ +│ {all generated content here} │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Examples + +### Example 1: New AGENTS.md (no existing file) + +```markdown + +## Agentic-OS Generated Rules + +### Project Context + +This is a Go microservices project with 3 services. + +### Quality Gates + +- Run `go test ./...` before completing work +- Run `golangci-lint run` for code quality +- Ensure new packages have corresponding test files + + +``` + +### Example 2: Extending existing AGENTS.md (Complex tier) + +User's existing content (preserved as-is): +```markdown +# Team Agents + +## Product Manager +Responsible for roadmap decisions... + +## Tech Lead +Responsible for architecture decisions... +``` + +After agentic-os extension: +```markdown +# Team Agents + +## Product Manager +Responsible for roadmap decisions... + +## Tech Lead +Responsible for architecture decisions... + + +## Agentic-OS Generated Rules + +### Personas + +#### Architect +**Scope:** `/Designs/` +**Focus:** System design, scalability, requirements traceability +**Behavioral rules:** +- Prioritize structural patterns over quick fixes +- Reference existing blueprints before proposing new structures + +#### Operations Specialist +**Scope:** `/Operations/` +**Focus:** Process efficiency, documentation completeness +**Behavioral rules:** +- Follow documentation standards +- Enforce cross-reference rules + +### Scope Boundaries + +| Domain | Isolated From | Rationale | +|--------|--------------|-----------| +| Designs/ | Operations/ | Architecture and HR are independent | +| Operations/ | Designs/ | Recruitment is independent of design | + +### Cross-References + +| Source | Target | Link Format | +|--------|--------|-------------| +| Operations/interviews/ | Operations/job-descriptions/ | `Job-ID: jd-*` | + + +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Antigravity as a runtime. It formats the assembled proposal (from templates) into AGENTS.md content within managed block markers, preserving any existing user content above the block. diff --git a/.agents/skills/agentic-os-setup/adapters/claude.md b/.agents/skills/agentic-os-setup/adapters/claude.md new file mode 100644 index 0000000..da09b94 --- /dev/null +++ b/.agents/skills/agentic-os-setup/adapters/claude.md @@ -0,0 +1,86 @@ +# Adapter: Claude Code + +## Purpose + +Describes how to format agentic-os generated output for Claude Code consumption. + +## File Path Convention + +- **Primary:** `CLAUDE.md` at repo root +- **If CLAUDE.md already exists:** Create `CLAUDE-agentic-os.md` as a companion file. Never modify the existing CLAUDE.md. + +## Format Specification + +Claude Code reads CLAUDE.md as a markdown file with freeform structure. Effective patterns: + +- Use `##` headers to organize sections (Persona Routing, Scope Isolation, Quality Gates, etc.) +- Bullet lists for rules and constraints +- Code blocks for commands and patterns +- Keep instructions direct and imperative ("Do X", "Never Y") + +## Constraints + +- Single file (no directory structure like Cursor) +- No frontmatter or metadata — pure markdown +- No glob-based routing — all rules apply globally (Claude Code doesn't have file-scoped rules) +- Rules must be self-describing (include "when editing in X" context inline) + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No CLAUDE.md exists | Create `CLAUDE.md` | +| CLAUDE.md exists | Create `CLAUDE-agentic-os.md` as companion. Add a note at top: "This file supplements the existing CLAUDE.md with agentic-os configuration." | + +Never modify an existing CLAUDE.md. + +## Examples + +### Example 1: Simple Tier (single-purpose project) + +```markdown +# Project Context + +This is a Python FastAPI project using pytest for testing. + +## Quality Gates + +Before completing work: +- Run tests: `pytest` +- Run type checking: `mypy src/` +- Run formatting: `ruff format --check .` + +## Project Structure + +- `src/` — Application source (FastAPI routes and models) +- `tests/` — Test files (pytest) +- `alembic/` — Database migrations +``` + +### Example 2: Multi Tier (multiple concerns) + +```markdown +# Agentic-OS Configuration + +## Persona Routing + +- **Backend Mode:** Triggered when editing `/backend/`. Focus on API design, data modeling, and performance. +- **Frontend Mode:** Triggered when editing `/frontend/`. Focus on component architecture, accessibility, and UX. +- **DevOps Mode:** Triggered when editing `/infra/`. Focus on reliability, security, and cost optimization. + +## Scope Isolation + +Do not cross-reference between isolated domains unless explicitly asked: +- `/backend/` and `/frontend/` have distinct conventions +- `/infra/` is independent from application code + +## Quality Gates + +- Backend: `cd backend && pytest && mypy .` +- Frontend: `cd frontend && npm test && npm run lint` +- Infrastructure: `cd infra && terraform validate` +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Claude Code as a runtime. It formats the assembled proposal (from templates) into Claude-appropriate markdown, respecting the constraints above. diff --git a/.agents/skills/agentic-os-setup/adapters/cline.md b/.agents/skills/agentic-os-setup/adapters/cline.md new file mode 100644 index 0000000..8ea84b8 --- /dev/null +++ b/.agents/skills/agentic-os-setup/adapters/cline.md @@ -0,0 +1,85 @@ +# Adapter: Cline + +## Purpose + +Describes how to format agentic-os generated output for Cline AI consumption. + +## File Path Convention + +- **Primary:** `.clinerules` at repo root +- **If `.clinerules` already exists:** Create `.clinerules-agentic-os` as a companion file. Never modify the existing `.clinerules`. + +## Format Specification + +Cline reads `.clinerules` as a plain text/markdown file containing behavioral instructions. Effective patterns: + +- Use `##` headers to organize sections +- Direct imperative rules ("Always X", "Never Y", "When doing Z, ensure W") +- Bullet lists for grouped rules +- Keep language concise and actionable + +## Constraints + +- Single file (no directory-based rule system like Cursor) +- No frontmatter or metadata +- No glob-based routing — all rules apply globally +- Rules must be self-describing (include path context inline where needed) +- Simpler format than Claude or Cursor — focus on behavioral directives + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No `.clinerules` exists | Create `.clinerules` | +| `.clinerules` exists | Create `.clinerules-agentic-os` as companion. Never modify existing file. | + +## Examples + +### Example 1: Simple Tier + +```markdown +# Project Rules + +## Quality Gates + +- Always run `npm test` before completing work +- Always run `npm run lint` before completing work +- New source files must have corresponding test files + +## Project Structure + +- Source code lives in `src/` +- Tests live in `tests/` +- Follow existing naming conventions +``` + +### Example 2: Multi Tier + +```markdown +# Agentic-OS Rules + +## Persona Routing + +When working in `/backend/`: +- Focus on API design, data modeling, and performance +- Follow Python conventions (PEP 8, type hints) + +When working in `/frontend/`: +- Focus on component architecture and accessibility +- Follow React/TypeScript conventions + +## Scope Isolation + +- Do not suggest content from `/backend/` when working in `/frontend/` +- Do not suggest content from `/frontend/` when working in `/backend/` +- Keep suggestions scoped to the current domain + +## Quality Gates + +- Backend: run `pytest` and `mypy` before completing work +- Frontend: run `npm test` and `npm run lint` before completing work +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Cline as a runtime. It formats the assembled proposal (from templates) into Cline-appropriate rules, respecting the single-file, directive-focused format. diff --git a/.agents/skills/agentic-os-setup/adapters/cursor.md b/.agents/skills/agentic-os-setup/adapters/cursor.md new file mode 100644 index 0000000..594925c --- /dev/null +++ b/.agents/skills/agentic-os-setup/adapters/cursor.md @@ -0,0 +1,138 @@ +# Adapter: Cursor + +## Purpose + +Describes how to format agentic-os generated output for Cursor AI consumption via `.cursor/rules/` files. + +## File Path Convention + +- **Directory:** `.cursor/rules/` +- **Filename:** `NNN-agentic-os.mdc` or `NNN-agentic-os-{concern}.mdc` +- **Numbering:** Use the next available number in the appropriate band. Default to 900-band if no convention exists. If existing rules use a different band, append after the highest existing number. + +### Numbering Detection + +1. List all existing `.mdc` files in `.cursor/rules/` +2. Extract the numeric prefix from each filename +3. Identify the convention (e.g., 0XX=core, 1XX=tools, 8XX=workflow) +4. Place agentic-os rules in the highest available band (typically 900+) +5. Never renumber or move existing files + +## Format Specification + +Each `.mdc` file requires YAML frontmatter: + +```yaml +--- +description: Human-readable description of this rule's purpose +globs: path/to/files/**/*.ext +alwaysApply: true +--- +``` + +**Required fields:** +- `description` — Clear, concise explanation (shown in Cursor's rule list) +- `globs` — File patterns this rule applies to + +**Optional fields:** +- `alwaysApply` — Set to `true` when the rule should always be active for matched files + +**Body:** Markdown content after frontmatter contains the actual rules. + +## Constraints + +- Each file targets specific globs — rules are file-scoped, not global +- Globs must be specific: NEVER use `*` alone (too broad) +- One concern per file is preferred (persona routing separate from scope isolation) +- Keep individual files focused (under 50 lines of rule content) +- YAML frontmatter is mandatory + +## Glob Specificity Rules + +| Pattern | Acceptable? | Why | +|---------|:-----------:|-----| +| `src/**/*` | Yes | Targets specific directory | +| `**/*.ts` | Yes | Targets specific file type | +| `src/**/*.tsx` | Yes | Combines directory + type | +| `*` | No | Too broad — would match everything | +| `**/*` | No | Equivalent to matching all files | + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No `.cursor/rules/` directory | Create directory and add rule files starting at 900 | +| Directory exists with rules | Scan for glob collisions, use next available number | +| Glob collision detected | Report conflict, propose narrower glob or skip | + +Never modify or renumber existing `.mdc` files. + +## Collision Detection Protocol + +Before writing ANY .mdc file: +1. Read all existing `.mdc` files in `.cursor/rules/` +2. Extract each file's `globs` value from frontmatter +3. Compare proposed globs against existing globs +4. If overlap exists: report which file conflicts, what its glob is, and why they conflict +5. Propose alternatives: narrower glob, different file scope, or skip + +## Examples + +### Example 1: Simple project context + +```yaml +--- +description: Project context and quality gates for agentic-os +globs: src/**/* +alwaysApply: true +--- +# Project Standards + +This is a TypeScript project using Vitest for testing. + +When working in src/: +- Run `npm test` before considering work complete +- Run `npm run lint` to verify code style +- New files should have corresponding .test.ts files +``` + +### Example 2: Persona routing (Complex tier) + +```yaml +--- +description: Persona routing — Architecture domain +globs: Designs/**/* +alwaysApply: true +--- +# Architect Mode + +When working in Designs/: +- Prioritize structural scalability and system design patterns +- Reference AGENTS.md for full persona guidelines +- Cross-reference existing blueprints before proposing new designs +- Do not apply patterns from Operations/ or Infrastructure/ +``` + +### Example 3: Scope isolation (Complex tier) + +```yaml +--- +description: Scope isolation between concern domains +globs: Operations/**/*,Designs/**/*,Infrastructure/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in Operations/: +- Do not suggest content from Designs/ or Infrastructure/ + +When working in Designs/: +- Do not suggest content from Operations/ or Infrastructure/ + +When working in Infrastructure/: +- Do not suggest content from Operations/ or Designs/ +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Cursor as a runtime. It formats the assembled proposal (from templates) into Cursor-native `.mdc` files, respecting numbering conventions, glob specificity, and collision detection requirements. diff --git a/.agents/skills/agentic-os-setup/agents/openai.yaml b/.agents/skills/agentic-os-setup/agents/openai.yaml new file mode 100644 index 0000000..d13d161 --- /dev/null +++ b/.agents/skills/agentic-os-setup/agents/openai.yaml @@ -0,0 +1,5 @@ +name: agentic-os-setup +description: AI-assisted repo setup — scans structure, classifies complexity, proposes configuration proportional to detected needs. Use when setting up agentic-os on an existing project. +version: 1 +invocation: + trigger: implicit diff --git a/.agents/skills/agentic-os-setup/catalog.md b/.agents/skills/agentic-os-setup/catalog.md new file mode 100644 index 0000000..613ec51 --- /dev/null +++ b/.agents/skills/agentic-os-setup/catalog.md @@ -0,0 +1,213 @@ +# Signal Catalog + +## Purpose + +Structured reference of known filesystem patterns and their meanings. The AI uses this catalog to anchor detection during repo scanning. Patterns not listed here do not prevent the AI from reasoning about novel structures — this is a reference, not a hard gate. + +--- + +## Signal: .cursor/rules/ + +**Pattern:** Directory `.cursor/rules/` exists with `.mdc` files +**Indicates:** Existing Cursor AI configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Scan existing rules for glob patterns (collision detection) +- Detect numbering convention (respect existing band) +- Generate agentic-os rule in next available number slot +**Coexistence:** Additive only — never modify existing rules + +--- + +## Signal: CLAUDE.md + +**Pattern:** File `CLAUDE.md` at repo root +**Indicates:** Existing Claude Code configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Do not overwrite — create `CLAUDE-agentic-os.md` as companion file +- Reference companion from proposal +**Coexistence:** Companion file pattern + +--- + +## Signal: .clinerules + +**Pattern:** File `.clinerules` at repo root +**Indicates:** Existing Cline configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Do not overwrite — create `.clinerules-agentic-os` as companion file +**Coexistence:** Companion file pattern + +--- + +## Signal: AGENTS.md + +**Pattern:** File `AGENTS.md` at repo root +**Indicates:** Existing agent instructions (possibly Antigravity or hand-written) +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Extend with managed block (append below existing content) +- Never replace or modify existing content +**Coexistence:** Managed block append pattern + +--- + +## Signal: _bmad/ + +**Pattern:** Directory `_bmad/` at repo root +**Indicates:** BMad agent framework installed +**Complexity impact:** Automatically Complex tier (framework presence) +**Setup implications:** +- Defer persona routing entirely to BMAD +- Only generate: scope isolation, cross-reference, naming enforcement +- Explain deferral in proposal +**Coexistence:** Defer persona ownership + +--- + +## Signal: .claude/ + +**Pattern:** Directory `.claude/` at repo root +**Indicates:** Claude Code project configuration or skills +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Inspect for skills/ subdirectory +- Note existing configuration approach +**Coexistence:** Do not modify contents + +--- + +## Signal: package.json + +**Pattern:** File `package.json` at repo root +**Indicates:** Node.js/JavaScript project +**Complexity impact:** +1 concern folder (if workspaces found: +1 per workspace root) +**Setup implications:** +- Check for `workspaces` field (monorepo indicator → Multi or Complex) +- Detect test framework (jest, vitest, mocha) for quality gate template +- Note scripts for build/test/lint commands +**Coexistence:** Read-only reference + +--- + +## Signal: pyproject.toml + +**Pattern:** File `pyproject.toml` at repo root +**Indicates:** Python project (modern packaging) +**Complexity impact:** +1 concern folder +**Setup implications:** +- Check for monorepo tools (hatch workspaces, pants) +- Detect test framework (pytest, unittest) +- Note linting tools (ruff, black, mypy) +**Coexistence:** Read-only reference + +--- + +## Signal: Cargo.toml + +**Pattern:** File `Cargo.toml` at repo root +**Indicates:** Rust project +**Complexity impact:** +1 concern folder (if workspace: +1 per member) +**Setup implications:** +- Check for `[workspace]` section (monorepo indicator) +- Note crate structure for scope isolation +**Coexistence:** Read-only reference + +--- + +## Signal: go.mod + +**Pattern:** File `go.mod` at repo root +**Indicates:** Go project +**Complexity impact:** +1 concern folder +**Setup implications:** +- Check for go.work (multi-module workspace) +- Note module path for naming conventions +**Coexistence:** Read-only reference + +--- + +## Signal: terraform/ + +**Pattern:** Directory `terraform/` or `infra/` with `.tf` files +**Indicates:** Infrastructure-as-Code component +**Complexity impact:** +1 concern folder +**Setup implications:** +- Distinct concern domain (infrastructure vs application code) +- Consider scope isolation between IaC and app code +- Note state backend for quality gate template +**Coexistence:** Read-only reference + +--- + +## Signal: docker-compose.yml + +**Pattern:** File `docker-compose.yml` or `docker-compose.yaml` at root +**Indicates:** Multi-service local development setup +**Complexity impact:** +1 concern folder (if 3+ services) +**Setup implications:** +- Indicates multiple services that may need scope isolation +- Service names can inform persona routing +**Coexistence:** Read-only reference + +--- + +## Signal: .github/ + +**Pattern:** Directory `.github/` with workflows/ +**Indicates:** GitHub Actions CI/CD pipeline +**Complexity impact:** Neutral (doesn't affect tier directly) +**Setup implications:** +- Note CI structure for quality gate template +- Detect workflow organization patterns +**Coexistence:** Read-only reference + +--- + +## Signal: docs/ + +**Pattern:** Directory `docs/` at root +**Indicates:** Documentation as a distinct concern +**Complexity impact:** +1 concern folder +**Setup implications:** +- Potential scope isolation (docs vs code) +- May indicate architectural documentation needs +**Coexistence:** Read-only reference + +--- + +## Signal: Makefile + +**Pattern:** File `Makefile` at repo root +**Indicates:** Build automation (often multi-concern orchestration) +**Complexity impact:** Neutral (indicator of maturity, not complexity) +**Setup implications:** +- Read target names for project structure hints +- Note common targets (build, test, lint, deploy) +**Coexistence:** Read-only reference + +--- + +## Signal: src/ + +**Pattern:** Directory `src/` at repo root (without other concern folders) +**Indicates:** Single-purpose project with conventional structure +**Complexity impact:** Neutral (alone = Simple tier cap) +**Setup implications:** +- If `src/` is the only concern folder, tier should not exceed Simple +- Common in libraries, CLI tools, single applications +**Coexistence:** Read-only reference + +--- + +## Usage Context + +The AI reads this catalog during the scanning phase to: +1. Identify which signals are present in the target repo +2. Map each signal to its complexity dimension contribution +3. Determine coexistence behavior before proposing any output +4. Anchor decisions in documented patterns rather than hallucination + +Signals not in this catalog can still be reasoned about — this catalog accelerates recognition of common patterns but does not limit the AI's analytical capability. diff --git a/.agents/skills/agentic-os-setup/examples/complex-output.md b/.agents/skills/agentic-os-setup/examples/complex-output.md new file mode 100644 index 0000000..73137f7 --- /dev/null +++ b/.agents/skills/agentic-os-setup/examples/complex-output.md @@ -0,0 +1,150 @@ +# Calibration Example: Complex Tier Output + +## Scenario + +A multi-concern monorepo with `Designs/`, `Operations/`, `Team-Workitems/`, `Infrastructure/`, and `docs/` at root. Existing `.cursor/rules/` (files 800-805), existing AGENTS.md. Two team indicators. Cross-references between Operations and Designs. + +**Detected signals:** .cursor/rules/ (6 files, 800-band), AGENTS.md, 5 concern folders, team indicators, cross-domain references +**Classification:** Complex (5+ concern folders, 4+ AI configs, 2 teams, 2+ cross-refs) +**Runtimes targeted:** claude, cursor, antigravity + +## Expected Output + +### File: CLAUDE-agentic-os.md (companion — existing CLAUDE.md untouched) + +```markdown +# Agentic-OS Configuration + +## Persona Routing + +- **Architect Mode:** Triggered when editing `/Designs/`. Prioritize structural scalability, system design patterns, and requirements traceability. +- **Operations Mode:** Triggered when editing `/Operations/`. Focus on process efficiency, candidate assessment, and documentation completeness. +- **Engineering Mode:** Triggered when editing `/Infrastructure/`. Focus on reliability, security, and operational readiness. + +See AGENTS.md for full persona definitions. + +## Scope Isolation + +The following domains are isolated — do not cross-reference unless explicitly asked: +- `/Designs/` and `/Operations/` are independent concerns +- `/Infrastructure/` and `/Team-Workitems/` are independent concerns + +## Cross-Reference Rules + +- **Operations/ → Designs/**: Interview files must reference a valid job description via `Job-ID:` frontmatter field +- **Team-Workitems/ → Designs/**: Work items should trace to design documents via `Design-Ref:` field + +## Naming Conventions + +### Operations/job-interviews/ +- Candidate files: `candidate_[first-name]-[last-name].md` + +### Team-Workitems/ +- Work items: `[priority]-[short-description].md` + +## Quality Gates + +Before completing work, verify: +- **Linting**: `make lint` +- **Tests**: `make test` +- **Cross-references**: Verify linked documents exist +``` + +### File: .cursor/rules/806-agentic-os-personas.mdc + +```yaml +--- +description: Persona routing for agentic-os domains — Designs +globs: Designs/**/* +alwaysApply: true +--- +# Architect Mode + +When working in Designs/: +- Prioritize structural scalability and system design metrics +- Reference AGENTS.md for architecture persona guidelines +- Cross-reference parent blueprints for requirements traceability +- Do not suggest patterns from Operations/ or Infrastructure/ +``` + +### File: .cursor/rules/807-agentic-os-isolation.mdc + +```yaml +--- +description: Scope isolation between concern domains +globs: Operations/**/*,Designs/**/*,Team-Workitems/**/*,Infrastructure/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in Operations/: +- Do not read or suggest content from Designs/ or Infrastructure/ +- Keep completions scoped to HR/recruitment conventions + +When working in Designs/: +- Do not read or suggest content from Operations/ or Team-Workitems/ +- Keep completions scoped to architecture patterns + +When working in Infrastructure/: +- Do not read or suggest content from Operations/ or Designs/ +- Keep completions scoped to IaC and deployment patterns +``` + +### File: AGENTS.md (extended via managed block — existing content preserved above) + +```markdown + +## Agentic-OS Generated Rules + +### Personas + +#### Architect +**Scope:** `/Designs/` +**Focus:** System design, scalability, requirements traceability +**Behavioral rules:** +- Prioritize structural patterns over quick fixes +- Reference existing blueprints before proposing new structures +- Validate against design principles in docs/ + +#### Operations Specialist +**Scope:** `/Operations/` +**Focus:** Process efficiency, documentation completeness, candidate assessment +**Behavioral rules:** +- Follow HR documentation standards +- Enforce cross-reference rules (interviews → job descriptions) +- Maintain naming conventions strictly + +#### Infrastructure Engineer +**Scope:** `/Infrastructure/` +**Focus:** Reliability, security, operational readiness +**Behavioral rules:** +- Validate against security baselines +- Consider blast radius of changes +- Reference runbooks for operational procedures + +### Scope Boundaries + +| Domain | Isolated From | Rationale | +|--------|--------------|-----------| +| Designs/ | Operations/, Team-Workitems/ | Architecture concerns are independent of HR operations | +| Operations/ | Designs/, Infrastructure/ | Recruitment is independent of system design | +| Infrastructure/ | Operations/, Designs/ | IaC has distinct safety requirements | + +### Cross-References + +| Source | Target | Link Format | Rule | +|--------|--------|-------------|------| +| Operations/job-interviews/ | Operations/job-descriptions/ | `Job-ID: jd-*` | Every interview file must link to a valid JD | +| Team-Workitems/ | Designs/ | `Design-Ref: *` | Work items should trace to design docs | + + +``` + +## Volume Calibration + +Complex tier output should be: +- Multiple config files per runtime (personas, isolation, cross-refs may be separate) +- AGENTS.md with full persona definitions and relationship tables +- 50-150 lines per major file +- Comprehensive organizational rules covering personas, isolation, cross-references, and naming +- Cursor rules in separate files by concern (personas, isolation) to avoid glob conflicts diff --git a/.agents/skills/agentic-os-setup/examples/simple-output.md b/.agents/skills/agentic-os-setup/examples/simple-output.md new file mode 100644 index 0000000..72a5545 --- /dev/null +++ b/.agents/skills/agentic-os-setup/examples/simple-output.md @@ -0,0 +1,65 @@ +# Calibration Example: Simple Tier Output + +## Scenario + +A single-purpose Node.js project with `src/`, `tests/`, `package.json`, and a `.github/workflows/` directory. No existing AI config. One developer. + +**Detected signals:** package.json (jest, eslint), src/, .github/ +**Classification:** Simple (1 concern folder, 0 AI configs, 0 teams, 0 cross-refs, no framework) +**Runtimes targeted:** claude, cursor + +## Expected Output + +### File: CLAUDE.md + +```markdown +# Project Context + +This is a Node.js project using Jest for testing and ESLint for linting. + +## Quality Gates + +Before completing work: +- Run tests: `npm test` +- Run linting: `npm run lint` +- Ensure new code has corresponding test coverage + +## Project Structure + +- `src/` — Application source code +- `tests/` — Test files (Jest) +- `.github/workflows/` — CI pipeline +``` + +### File: .cursor/rules/900-agentic-os.mdc + +```yaml +--- +description: Project context and quality gates for agentic-os +globs: src/**/* +alwaysApply: true +--- +# Project Standards + +This is a Node.js project. When working in src/: +- Run `npm test` before considering work complete +- Run `npm run lint` to verify code style +- New source files should have corresponding test files in tests/ +- Follow existing naming conventions in src/ +``` + +## What is NOT Generated (Simple Tier) + +- No AGENTS.md (not enough complexity for personas) +- No GOALS.md (not a multi-concern workspace) +- No persona routing (single domain) +- No scope isolation (single domain) +- No cross-reference enforcement (no relationships detected) + +## Volume Calibration + +Simple tier output should be: +- 1 file per targeted runtime +- Under 30 lines per file +- Focused on project context and quality gates only +- No organizational/behavioral rules diff --git a/.agents/skills/agentic-os-setup/templates/cross-reference.md b/.agents/skills/agentic-os-setup/templates/cross-reference.md new file mode 100644 index 0000000..e61e739 --- /dev/null +++ b/.agents/skills/agentic-os-setup/templates/cross-reference.md @@ -0,0 +1,61 @@ +# Template: Cross-Reference Enforcement + +## Intent + +Enforce that files in one domain correctly reference files in another domain where a declared relationship exists. Catches broken links, missing references, and orphaned documents. + +## Inputs Required + +- `{relationships}`: List of source → target relationships with their linking mechanism +- `{source_domain}`: Domain where the referencing file lives +- `{target_domain}`: Domain where the referenced file lives +- `{link_format}`: How the reference is expressed (frontmatter field, inline link, filename convention) + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Cross-reference enforcement — {source_domain} → {target_domain} +globs: {source_domain}/**/* +alwaysApply: true +--- +# Cross-Reference Rules + +Every file in `{source_domain}/` that matches `{file_pattern}` MUST: +- {reference_requirement_1} +- {reference_requirement_2} + +Validation: +- Check that referenced {target_domain} file exists +- Warn if reference format doesn't match: `{link_format}` +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Cross-Reference Rules + +{for each relationship} +- **{source_domain}/ → {target_domain}/**: Files matching `{file_pattern}` must contain a reference to a valid `{target_domain}` file using format: `{link_format}` +{end for} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Relationship Enforcement + +{for each relationship} +### {relationship_name} +**Source:** `/{source_domain}/{file_pattern}` +**Target:** `/{target_domain}/` +**Link format:** `{link_format}` +**Rule:** {enforcement_description} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** Cross-domain references found (e.g., interview files referencing job descriptions, work items referencing design docs, tests referencing source modules) +- **Requires:** User confirmation for AI-inferred relationships (only manifest-declared relationships are auto-included) diff --git a/.agents/skills/agentic-os-setup/templates/naming-enforcement.md b/.agents/skills/agentic-os-setup/templates/naming-enforcement.md new file mode 100644 index 0000000..b0b0890 --- /dev/null +++ b/.agents/skills/agentic-os-setup/templates/naming-enforcement.md @@ -0,0 +1,67 @@ +# Template: Naming Enforcement + +## Intent + +Enforce consistent file and directory naming conventions within a domain. Catches deviations from established patterns and guides creation of new files. + +## Inputs Required + +- `{domain}`: Domain path where naming rules apply +- `{patterns}`: List of naming patterns with their regex or description +- `{examples}`: Valid and invalid filename examples + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Naming conventions for {domain} +globs: {domain}/**/* +alwaysApply: true +--- +# Naming Conventions + +Files in `{domain}/` follow these patterns: + +{for each pattern} +- **{file_type}**: `{naming_pattern}` + Example: `{valid_example}` +{end for} + +When creating new files in this domain: +- Follow the naming pattern exactly +- Warn if a proposed filename doesn't match the convention +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Naming Conventions + +{for each domain_with_patterns} +### {domain}/ +{for each pattern} +- `{file_type}` files: `{naming_pattern}` (e.g., `{valid_example}`) +{end for} +{end for} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Naming Standards + +{for each domain_with_patterns} +### {domain} +| File Type | Pattern | Example | +|-----------|---------|---------| +{for each pattern} +| {file_type} | `{naming_pattern}` | `{valid_example}` | +{end for} +{end for} +``` + +## When to Use + +- **Complexity tier:** Simple, Multi, or Complex (applicable at any tier where patterns are detected) +- **Detected signals:** Consistent naming patterns observed in existing files (3+ files following same convention) +- **Common patterns:** kebab-case files, prefixed files (NNN-name.ext), date-prefixed (YYYY-MM-DD-name), type-prefixed (feat-*, fix-*) diff --git a/.agents/skills/agentic-os-setup/templates/persona-routing.md b/.agents/skills/agentic-os-setup/templates/persona-routing.md new file mode 100644 index 0000000..9c69303 --- /dev/null +++ b/.agents/skills/agentic-os-setup/templates/persona-routing.md @@ -0,0 +1,66 @@ +# Template: Persona Routing + +## Intent + +Route AI persona/behavior based on which folder the user is editing in. Each concern domain gets a distinct behavioral mode optimized for that domain's work. + +## Inputs Required + +- `{domains}`: List of detected concern domains with their folder paths +- `{personas}`: Mapping of domain → persona name and behavioral description +- `{repo_name}`: Repository name for context + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Persona routing for agentic-os domains — {domain_name} +globs: {domain_path}/**/* +alwaysApply: true +--- +# {persona_name} Mode + +When working in `{domain_path}/`: +- {persona_behavioral_rule_1} +- {persona_behavioral_rule_2} +- {persona_behavioral_rule_3} + +Reference AGENTS.md for full persona guidelines. +``` + +One .mdc file per domain. Each gets a specific glob. + +## Output Pattern (CLAUDE.md section) + +```markdown +## Persona Routing + +{for each domain} +- **{persona_name} Mode:** Triggered when editing `/{domain_path}/`. {persona_behavioral_summary} +{end for} + +See AGENTS.md for full persona definitions. +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Personas + +{for each domain} +### {persona_name} + +**Scope:** `/{domain_path}/` +**Focus:** {persona_focus_description} +**Behavioral rules:** +- {rule_1} +- {rule_2} +- {rule_3} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** 2+ distinct concern domains with different intent (e.g., `Designs/` + `Operations/` or `frontend/` + `backend/` + `infra/`) +- **NOT when:** Single-purpose repo, or `_bmad/` detected (defer persona ownership to BMAD) diff --git a/.agents/skills/agentic-os-setup/templates/quality-gates.md b/.agents/skills/agentic-os-setup/templates/quality-gates.md new file mode 100644 index 0000000..35d64c3 --- /dev/null +++ b/.agents/skills/agentic-os-setup/templates/quality-gates.md @@ -0,0 +1,72 @@ +# Template: Quality Gates + +## Intent + +Define quality checks that the AI should enforce or remind about when creating or modifying files within a domain. Derived from detected tooling (linters, test frameworks, CI pipelines). + +## Inputs Required + +- `{domain}`: Domain path or glob where quality gates apply +- `{gates}`: List of quality checks with their commands or descriptions +- `{test_framework}`: Detected test framework (jest, pytest, cargo test, go test, etc.) +- `{lint_tools}`: Detected linting/formatting tools +- `{ci_checks}`: Known CI pipeline checks + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Quality gates for {domain} +globs: {domain}/**/*.{extensions} +alwaysApply: true +--- +# Quality Gates + +Before considering work in `{domain}/` complete: + +{for each gate} +- [ ] {gate_description}: `{gate_command}` +{end for} + +When creating new files: +- Ensure they have corresponding test files (if test framework detected) +- Follow existing patterns for test file location and naming +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Quality Gates + +Before completing work, verify: + +{for each gate} +- **{gate_name}**: `{gate_command}` — {gate_purpose} +{end for} + +Test framework: {test_framework} +Test location: {test_directory_pattern} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Quality Standards + +### Pre-Completion Checklist +{for each gate} +- [ ] **{gate_name}**: {gate_description} + Command: `{gate_command}` +{end for} + +### Testing Requirements +- Framework: {test_framework} +- Location: `{test_directory_pattern}` +- Coverage: {coverage_expectations} +``` + +## When to Use + +- **Complexity tier:** Simple, Multi, or Complex +- **Detected signals:** Test framework present (package.json scripts, pytest.ini, Cargo.toml test config), linting tools configured (.eslintrc, ruff.toml, .golangci.yml), CI workflows present (.github/workflows/) +- **Scales with tier:** Simple = test + lint only; Multi/Complex = full gate set including build verification diff --git a/.agents/skills/agentic-os-setup/templates/scope-isolation.md b/.agents/skills/agentic-os-setup/templates/scope-isolation.md new file mode 100644 index 0000000..d3ba8e3 --- /dev/null +++ b/.agents/skills/agentic-os-setup/templates/scope-isolation.md @@ -0,0 +1,64 @@ +# Template: Scope Isolation + +## Intent + +Prevent AI from cross-contaminating context between unrelated concern domains. When working in one domain, the AI should not suggest content from or reference patterns in other domains unless explicitly asked. + +## Inputs Required + +- `{domains}`: List of domain paths that should be isolated from each other +- `{isolation_pairs}`: Specific pairs of domains that must not cross-reference + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Scope isolation between concern domains +globs: {domain_path_1}/**/*,{domain_path_2}/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in `{domain_path_1}/`: +- Do not read or suggest content from {other_domains} +- Do not apply patterns from {other_domains} to this domain +- Keep completions scoped to this domain's conventions + +When working in `{domain_path_2}/`: +- Do not read or suggest content from {other_domains} +- Do not apply patterns from {other_domains} to this domain +- Keep completions scoped to this domain's conventions +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Scope Isolation + +The following domains are isolated — do not cross-reference unless explicitly asked: + +{for each isolation_pair} +- `/{domain_a}/` and `/{domain_b}/` are independent concerns +{end for} + +When editing in one domain, restrict suggestions and completions to that domain's patterns and conventions. +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Scope Boundaries + +{for each domain} +### {domain_name} +**Path:** `/{domain_path}/` +**Isolated from:** {list_of_other_domains} +**Rationale:** {why_these_are_separate_concerns} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** 2+ concern domains that serve different purposes (e.g., infrastructure vs application code, documentation vs implementation) +- **Always pair with:** Persona Routing (if personas are generated, isolation prevents persona bleed) diff --git a/.gitignore b/.gitignore index 7b384a9..84bd631 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,6 @@ Thumbs.db *~ .vscode/ .idea/ + +# Test results (generated output, not tracked) +tests/results/ diff --git a/CLAUDE.md b/CLAUDE.md index 43c994c..b8d798f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1,6 @@ @AGENTS.md + +## Skills + +Canonical skills are available at `.agents/skills/*/SKILL.md` (also accessible via `.claude/skills/`). +To run a skill: read its SKILL.md and follow the instructions within. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a7c0247 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,215 @@ +# Contributing to Agentic-OS + +Thank you for your interest in contributing! This guide covers how to add features, fix bugs, and extend the AI-installer skill system. + +## License + +This project is licensed under [CC BY-NC-SA 4.0](LICENSE). By contributing, you agree that your contributions will be licensed under the same terms. + +## Development Workflow + +1. **Fork** the repository +2. **Create a feature branch** from `main` +3. **Make your changes** following the patterns below +4. **Test manually** across at least one AI runtime (see Testing section) +5. **Submit a PR** with a clear description of what changed and why + +## Project Structure + +``` +agentic-os/ +├── setup.sh # Entry point — shell bootstrap +├── .agents/ +│ └── skills/ +│ ├── / # 47 canonical skills +│ └── agentic-os-setup/ # AI-installer skill (this feature) +│ ├── SKILL.md # Orchestrator — AI reads this first +│ ├── catalog.md # Signal catalog (known repo patterns) +│ ├── agents/openai.yaml # Agent Skills open standard metadata +│ ├── templates/ # Rule templates the AI fills +│ ├── adapters/ # Per-runtime output formatting +│ └── examples/ # Calibration examples +├── examples/ # Test repo fixtures (UJ-1 through UJ-4) +│ ├── uj-1-node-monorepo/ # Node.js monorepo with Cursor rules +│ ├── uj-2-architect-monorepo/ # Complex multi-concern with BMAD +│ ├── uj-3-flask-simple/ # Simple Flask project +│ └── uj-4-rust-antigravity/ # Rust workspace with AGENTS.md +├── tests/ # Automated test suite +│ ├── test_setup.sh # Shell tests (flag parsing, routing) +│ ├── test_content.py # Python tests (content validation) +│ └── results/ # Test output (gitignored) +├── Workflows/ # Daily and strategic workflows +├── Tutorials/ # Learning guides +├── Evals/ # Validation scripts and fixtures +└── System/ # MCP server, integrations, templates +``` + +## How to Contribute + +### Adding a Signal to the Catalog + +Signals are filesystem patterns that indicate something about a repo's structure. To add one: + +1. Edit `.agents/skills/agentic-os-setup/catalog.md` +2. Add an entry following this format: + +```markdown +## Signal: + +**Pattern:** +**Indicates:** +**Complexity impact:** <+1 tier signal, neutral, or -1> +**Setup implications:** +- +**Coexistence:** +``` + +3. Test: invoke the AI-installer on a repo containing this pattern and verify it's detected + +### Adding a Rule Template + +Rule templates define output patterns the AI fills with detected values. To add one: + +1. Create a new file in `.agents/skills/agentic-os-setup/templates/` +2. Follow this structure: + +```markdown +# Template: + +## Intent + + +## Inputs Required +- {variable}: + +## Output Pattern (Cursor .mdc) + + +## Output Pattern (CLAUDE.md section) + + +## Output Pattern (AGENTS.md section) + + +## When to Use +- Complexity tier: +- Detected: +- NOT when: +``` + +3. Test: verify the AI generates correct output from this template for each runtime + +### Adding a Runtime Adapter + +Adapters teach the AI how to format output for a specific tool. To add one: + +1. Create a new file in `.agents/skills/agentic-os-setup/adapters/` +2. Include: + - File path convention (where output goes for this runtime) + - Format specification (what valid output looks like) + - Constraints (what this runtime can/cannot express) + - Merge behavior (create new file vs extend existing) + - Examples (2-3 concrete output samples) + +3. Update `setup.sh` to accept the new runtime name in `--runtime` validation +4. Test: run the AI-installer targeting only this runtime on a sample repo + +### Modifying setup.sh + +The shell script handles bootstrapping and teardown. It: +- Parses flags (`--ai`, `--runtime`, `--dry-run`, `--track`, `--target`, `--auto`, `--remove`, `--help`) +- Bootstraps workspace infrastructure into the target (dirs, BACKLOG.md, Workflows/, skills, symlinks, .gitignore, CLAUDE.md skills reference) +- Writes the context bridge file (`.agents/.agentic-os-setup-context.json`) +- Prints invocation instructions (`/agentic-os-setup` for Claude Code, or "Run the agentic-os-setup skill" for others) +- Handles clean uninstall (reading manifest, deleting tracked files) + +Rules: +- POSIX sh compatible (no bashisms) +- No external dependencies beyond git, jq (for --remove), and standard Unix utilities +- Never add AI logic to the script — that belongs in SKILL.md + +### Modifying SKILL.md + +The orchestrator is the most sensitive file. Changes should: +- Maintain the section order (mode detection → scan → classify → propose → approve → write) +- Not break any of the 4 supported runtimes +- Preserve the non-destructive file policy (never modify user files) +- Keep the approval gate (never write without human confirmation) + +## Testing + +### Automated Tests + +The project includes two automated test layers: + +```bash +# Shell tests — validates setup.sh flag parsing, routing, and remove logic +sh tests/test_setup.sh + +# Python tests — validates content structure (manifest schema, .mdc frontmatter, markers) +pytest tests/test_content.py +``` + +Test results are written to `tests/results/` (gitignored): +- Shell: `tests/results/shell/report.txt` (plaintext pass/fail summary) +- Python: `tests/results/python/report.xml` (JUnit XML, configured in `pytest.ini`) + `tests/results/python/report.txt` (plaintext, generated by `tests/conftest.py`) + +The shell tests require only `sh`, `jq`, and standard POSIX tools. The Python tests require `pytest` and `pyyaml`. + +### Test Fixtures + +The `examples/` directory contains real repo structures for each user journey: +- `uj-1-node-monorepo/` — Node.js monorepo with 3 existing Cursor rules +- `uj-2-architect-monorepo/` — Complex multi-concern with BMAD, 10 Cursor rules, existing AGENTS.md +- `uj-3-flask-simple/` — Simple Flask project with no AI config +- `uj-4-rust-antigravity/` — Rust workspace with existing AGENTS.md + +Use these with `--target` to test setup.sh against specific scenarios. The script bootstraps workspace infrastructure and the skill into the target, then you invoke it locally: +```bash +./setup.sh --ai --target examples/uj-3-flask-simple --runtime claude +# Then open the target in your AI tool: /agentic-os-setup (Claude Code) or "Run the agentic-os-setup skill" +``` + +### Manual Testing Protocol + +AI behavior is non-deterministic, so the AI-installer skill also requires manual validation: + +1. **Run setup** against a fixture or real repo: `./setup.sh --ai --runtime ` +2. **Invoke the skill** in your AI runtime of choice +3. **Verify:** + - Correct complexity tier detected + - Appropriate output proposed (not over/under-generating) + - Dry-run shows accurate diffs + - No conflicts with existing configs + - Generated files are valid for their target runtime + - `setup.sh --remove` cleanly removes everything +4. **Test coexistence** (if applicable): + - Existing .cursor/rules/ are untouched + - Existing AGENTS.md is extended, not replaced + - _bmad/ detection triggers persona deferral + +### Evals + +For changes to canonical skills (not the AI-installer), run the existing eval suite: + +```bash +python scripts/validate_skills.py +python scripts/run_skill_evals.py --provider fixture +python scripts/run_routing_evals.py +``` + +## What Makes a Good PR + +- **Atomic:** One concern per PR (a signal, a template, an adapter — not all at once) +- **Tested:** Evidence that you ran the manual testing protocol +- **Documented:** If you add a signal, template, or adapter, the PR description shows example input → output +- **Non-breaking:** Classic `setup.sh` (no flags) behavior is unchanged +- **No secrets:** Generated configs can expose repo structure — never include real project data in examples + +## Code of Conduct + +Be respectful, constructive, and collaborative. This is a community project — treat others as you'd want to be treated. Harassment, discrimination, and toxic behavior will not be tolerated. + +## Questions? + +Open an issue with the `question` label if you're unsure about an approach before investing time in a PR. diff --git a/README.md b/README.md index 02b580a..d68029d 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,31 @@ cd personal-os ``` -2. **Run setup** +2. **Run setup** (choose your path) ```bash chmod +x setup.sh + + # Classic interactive setup (simple projects, greenfield workspaces) ./setup.sh + + # AI-assisted setup (existing projects, complex repos) + ./setup.sh --ai --runtime claude,cursor + + # Run against a different directory (bootstraps workspace + skill into target) + ./setup.sh --ai --target ./my-project --runtime claude + + # Unattended auto-approval (requires explicit --runtime) + ./setup.sh --ai --auto --runtime claude,cursor ``` + After running `--ai`, invoke the skill in your AI tool: `/agentic-os-setup` (Claude Code) or "Run the agentic-os-setup skill" (other runtimes). + + **When to use which:** + - **Classic** — Starting fresh or simple single-purpose projects + - **AI-assisted** — Existing projects with multiple concerns, existing AI configs, or team structures. The AI scans your repo, classifies complexity, and proposes configuration proportional to your needs. + - **Auto mode** (`--auto`) — CI/scripted environments where you trust the AI's proposal. Requires explicit `--runtime`. Shows the preview then writes without pausing for approval. + - **Target** (`--target `) — Run setup against a repo without cd'ing into it. Bootstraps workspace and skill into the target so the AI finds everything locally. + 3. **Start using** This automates high-leverage execution end-to-end: it converts raw backlog into prioritized, goal-aligned, verification-enforced action plans. ``` @@ -42,6 +61,7 @@ flowchart TD U["User Prompt"] --> A["Agent Runtime
Claude Code | Codex | Pi | OpenClaw"] A --> I["Instructions
AGENTS.md + wrappers"] A --> S["Skills
.agents/skills/*/SKILL.md"] + A --> AI["AI-Installer Skill
.agents/skills/agentic-os-setup/"] A --> W["Workflows
Workflows/*.md"] A --> F["State + Context
Tasks, GOALS, BACKLOG, Knowledge, Resources"] A -. optional .-> M["MCP Integrations
System/mcp + external services"] @@ -50,22 +70,63 @@ flowchart TD classDef core fill:#ff9891,stroke:#2b2b2b,color:#111111,stroke-width:1.2px; classDef optional fill:#ffd4d0,stroke:#2b2b2b,color:#111111,stroke-width:1.2px,stroke-dasharray: 4 3; - class U,A,I,S,W,F,E core; + class U,A,I,S,W,F,E,AI core; class M,D optional; ``` +### AI-Assisted Setup Flow + +```mermaid +flowchart LR + S["setup.sh --ai"] --> V["Verify skill exists"] + V --> C["Write context bridge"] + C --> P["Print invocation instructions"] + P --> U["User invokes AI"] + U --> SC["Scan repo structure"] + SC --> CL["Classify complexity"] + CL --> PR["Propose configuration"] + PR --> D{"Approve?"} + D -->|Yes| W["Write files + manifest"] + D -->|Selective| W + D -->|No| X["Exit, nothing written"] + D -->|Dry-run| DR["Show diffs only"] + D -->|Auto| W + + classDef action fill:#ff9891,stroke:#2b2b2b,color:#111111,stroke-width:1.2px; + classDef decision fill:#ffd4d0,stroke:#2b2b2b,color:#111111,stroke-width:1.2px; + class S,V,C,P,U,SC,CL,PR,W,X,DR action; + class D decision; +``` + +--- + +## Setup Modes + +| Mode | Command | When to Use | +|------|---------|-------------| +| Classic | `./setup.sh` | Greenfield workspace, simple projects, first-time users | +| AI-assisted | `./setup.sh --ai` | Existing repos, multiple concerns, existing AI configs | +| Targeted | `./setup.sh --ai --target ./path` | Run against a different repo without cd (bootstraps workspace locally) | +| Auto | `./setup.sh --ai --auto --runtime claude` | Unattended/scripted use (requires explicit `--runtime`) | +| Dry-run | `./setup.sh --ai --dry-run` | Preview proposals without writing anything | +| Remove | `./setup.sh --remove` | Clean uninstall of all generated files | + --- ## Agent Compatibility -Personal OS is designed to work with Claude Code, Codex, Pi, OpenClaw, and similar coding agent runtimes. +Personal OS is designed to work with Claude Code, Codex, Pi, OpenClaw, Cursor, Cline, Antigravity, and similar coding agent runtimes. - Shared behavior: `AGENTS.md` - Claude wrapper: `CLAUDE.md` - Codex wrapper: `CODEX.md` - Pi wrapper: `PI.md` - OpenClaw wrapper: `OPENCLAW.md` +- Cursor: `.cursor/rules/*.mdc` +- Cline: `.clinerules` +- Antigravity: `AGENTS.md` (shared) - Canonical runtime skills: `.agents/skills/*/SKILL.md` +- **AI-assisted setup** supports targeting specific runtimes: `./setup.sh --ai --runtime claude,cursor,cline,antigravity` - Skills in this repo follow the [Agent Skills open standard](https://agentskills.io/home). - This repo uses skills with progressive disclosure to manage context efficiently: agents begin with each skill's metadata (`name`, `description`, file path, plus `agents/openai.yaml`), and load full `SKILL.md` instructions only when a skill is selected. Canonical skills live in `.agents/skills/`, with bridge paths for Claude, Pi, and OpenClaw. - Optional subagents are supported when the runtime provides agent delegation features (not required for core repo operation). @@ -105,6 +166,9 @@ personal-os/ ├── Resources/ # Voice samples, templates, references ├── Workflows/ # Daily + Product & Strategy workflows ├── .agents/skills/ # Canonical Codex/OpenAI skill packs +│ └── agentic-os-setup/ # AI-installer skill (scan, classify, propose, write) +├── examples/ # Test repo fixtures (UJ-1 through UJ-4) +├── tests/ # Automated test suite (shell + Python) ├── Evals/ # Session reviews ├── Tutorials/ # Learning guides └── System/ # MCP server, templates, integrations diff --git a/_bmad-output/prd-ai-assisted-setup-2026-06-20/.decision-log.md b/_bmad-output/prd-ai-assisted-setup-2026-06-20/.decision-log.md new file mode 100644 index 0000000..b4a0a4e --- /dev/null +++ b/_bmad-output/prd-ai-assisted-setup-2026-06-20/.decision-log.md @@ -0,0 +1,46 @@ +# Decision Log — AI-Assisted Complex Repo Auto-Setup PRD + +## DL-1: Scope locked to Phase 1 MVP +**Decision:** PRD covers Phase 1 (MVP) only. Phase 2-4 acknowledged as future work in Non-Goals. +**Rationale:** Brainstorming senior review explicitly recommended shipping Phase 1 only: complexity detection, dry-run, conflict detection, uninstall. Avoids scope creep. +**Date:** 2026-06-20 + +## DL-2: Public open-source contribution framing +**Decision:** PRD written for upstream PR to itseffi/agentic-os. No company-specific patterns, tools, or references. +**Rationale:** This is a public open-source contribution. Internal reference repos inform design thinking but are never referenced directly in deliverables. +**Date:** 2026-06-20 + +## DL-3: AI-as-installer is the core paradigm +**Decision:** The setup is an AI skill, not a shell script doing the work. `setup.sh --ai` is a bootstrap that drops the skill; the AI executes. +**Rationale:** User explicitly chose "AI-assisted with instructions" over static scanning. First principles confirmed: "setup IS the first use." +**Date:** 2026-06-20 + +## DL-4: Mandatory runtimes for v1 +**Decision:** Claude Code, Cursor, Cline, Antigravity. Others (Copilot, Kiro, Codex, Pi) are future. +**Rationale:** User's issue explicitly lists these four as mandatory starting set. +**Date:** 2026-06-20 + +## DL-5: Backwards compatibility via flag +**Decision:** `setup.sh` without flags = current behavior unchanged. `--ai` enables advanced path. +**Rationale:** Zero regression risk for existing users. Reviewer-friendly for upstream maintainer. +**Date:** 2026-06-20 + +## DL-6: Generated files gitignored by default +**Decision:** AI-generated configs are added to .gitignore unless user passes `--track`. +**Rationale:** Security concern from architect persona — generated configs can expose team structure, tool usage patterns. +**Date:** 2026-06-20 + +## DL-7: Target directory flag +**Decision:** `--target ` enables running setup against any directory. All operations resolve relative to target. Default: CWD. +**Rationale:** Enables running tests against fixture repos (`setup.sh --ai --target examples/uj-1-node-monorepo`) and supports users who don't want to cd into their project directory. +**Date:** 2026-06-20 + +## DL-8: Auto-approval mode requires explicit runtime +**Decision:** `--auto` bypasses the approval gate (shows preview, writes immediately) but REQUIRES `--runtime` to be specified. Cannot auto-detect in unattended mode. +**Rationale:** Auto-detection relies on AI reasoning about which runtimes are present — this is non-deterministic and unsafe for unattended execution. Explicit runtime ensures predictable output. On conflict in auto mode: hard fail (non-zero exit) rather than silent overwrite. +**Date:** 2026-06-20 + +## DL-9: Dual test runner strategy +**Decision:** Shell tests (POSIX sh) for CLI behavior + Python tests (pytest) for content validation. Real directory structure fixtures for UJ-1 through UJ-4. Results in `tests/results/` (gitignored). +**Rationale:** Shell tests keep the CLI layer dependency-free (no Python needed to validate flag parsing). Python tests enable structured validation (JSON schema, YAML parsing, regex) that would be painful in pure sh. Real fixtures (not mocks) enable true end-to-end testing via `--target`. +**Date:** 2026-06-20 diff --git a/_bmad-output/prd-ai-assisted-setup-2026-06-20/addendum.md b/_bmad-output/prd-ai-assisted-setup-2026-06-20/addendum.md new file mode 100644 index 0000000..b711da6 --- /dev/null +++ b/_bmad-output/prd-ai-assisted-setup-2026-06-20/addendum.md @@ -0,0 +1,141 @@ +# Addendum — AI-Assisted Complex Repo Auto-Setup + +## Rule Template Examples (for Architecture Phase) + +These are the types of rules the AI-installer generates, with example output per runtime. + +### Persona Routing by Folder + +**Intent:** When editing in /Designs, adopt Architect persona. When in /Operations, adopt Talent Acquisition persona. + +**Cursor (.mdc):** +```yaml +--- +description: Persona routing for agentic-os domains +globs: Designs/**/* +alwaysApply: true +--- +# Architect Mode +- Prioritize structural scalability and system design metrics +- Reference AGENTS.md for architecture persona guidelines +- Cross-reference parent blueprints for requirements traceability +``` + +**Claude (CLAUDE.md section):** +```markdown +## Persona Routing +- **Architect Mode:** Triggered when editing `/Designs/`. Prioritize structural scalability. +- **Talent Acquisition Mode:** Triggered when processing `/Operations/`. Focus on assessment rubrics. +``` + +### Scope Isolation + +**Intent:** Do not suggest completions from /Operations while working in /Designs. + +**Cursor (.mdc):** +```yaml +--- +description: Scope isolation between concern domains +globs: Operations/**/*,Designs/**/*,Team-Workitems/**/* +alwaysApply: true +--- +# Cross-Domain Isolation +- Do not read or suggest content from /Operations/ while user is in /Designs/ or /Team-Workitems/ +- Do not read or suggest content from /Designs/ while user is in /Operations/ +``` + +### Cross-Reference Enforcement + +**Intent:** Interview notes must link to job descriptions. + +**Cursor (.mdc rule within the Operations glob):** +```markdown +- Every file in job-interviews/ MUST contain frontmatter linking to a valid file in job-descriptions/ (e.g., `Job-ID: jd-senior-frontend-01`) +``` + +### Naming Pattern Enforcement + +**Intent:** Candidate files follow exact format. + +```markdown +- Files in job-interviews/ follow format: `candidate_[first-name]-[last-name].md` +``` + +--- + +## Complexity Tier Scoring Algorithm + +### Scoring Model + +The AI uses a **highest-dimension-wins** algorithm: each dimension independently suggests a tier, and the overall classification is the HIGHEST tier suggested by any single dimension. This prevents under-classifying repos that are complex in one dimension but simple in others. + +### Dimension Scoring Table + +| Dimension | Zero | Simple | Multi | Complex | +|-----------|------|--------|-------|---------| +| Top-level concern folders | 0 | 1-2 | 3-4 | 5+ | +| Existing AI config files | 0 | 0-1 | 2-3 | 4+ | +| Team/group indicators | 0 | 0 | 1 | 2+ | +| Cross-domain references detected | 0 | 0 | 1 | 2+ | +| Agent framework present (_bmad/, etc.) | No | No | No | Yes | + +### Algorithm + +1. For each dimension, map the detected count to a tier (Zero=0, Simple=1, Multi=2, Complex=3) +2. Take the maximum score across all dimensions +3. If max score = 0 → Zero tier; 1 → Simple; 2 → Multi; 3 → Complex +4. Present the classification WITH the scoring breakdown so the user can challenge it + +### Override Protocol + +The AI always proposes its classification with rationale. The user can override up or down. The override is respected without argument. This prevents the "I know my repo better than you" frustration. + +### Calibration Notes + +- A repo with `_bmad/` is automatically Complex (framework presence is a strong signal) +- A repo with only `src/` and `tests/` should never exceed Simple regardless of file count +- The 15+ signals in catalog.md feed INTO these 5 dimensions (many signals map to "concern folders" count) + +--- + +## Rejected Alternatives + +### "Single SETUP.md as universal entry point" (Trigger #1) +**Rejected because:** Lower discoverability. Users don't know to say "read SETUP.md." The setup.sh bootstrap provides a concrete entry point everyone understands. + +### "Purely static pattern scanner" (Detection #1) +**Rejected because:** Too brittle for novel repo structures. Can't reason about intent, only match known patterns. AI-assisted approach handles the long tail. + +### "All-or-nothing runtime targeting" +**Rejected because:** Persona stress tests showed users often only use 1-2 runtimes. Generating configs for unused tools creates noise and confusion. + +### "Config files committed by default" +**Rejected because:** Architect persona identified security concern — generated configs can expose internal team structure, tool usage, ADO project names. Gitignore by default; opt-in to track. + +--- + +## Phase Roadmap (High-Level) + +| Phase | Scope | Key Capability | +|-------|-------|---------------| +| 1 (MVP) | This PRD | First-run, dry-run, conflict detection, uninstall | +| 2 | Re-run & teams | Delta merging, managed blocks, team isolation, BMAD deep integration | +| 3 | Integrations | MCP detection, relationship graph visualization, ADO/Jira awareness | +| 4 | Dynamic config | Ephemeral context generation, continuous adaptation, session-aware config | + +--- + +## First Principles Insight (from brainstorming) + +The platonic ideal: no setup exists. The AI reads signals at session start and computes context on-the-fly. Config is a projection, not a source. Phase 4 moves toward this — but Phases 1-3 build the infrastructure (signal catalog, relationship model, runtime adapters) that makes dynamic generation possible later. The static files generated in Phase 1 are stepping stones, not the destination. + +--- + +## Reference Architecture Patterns (anonymized) + +These patterns were observed in production repos and inform the signal catalog and rule templates: + +1. **Multi-concern monorepo** — Designs/, Operations/, Team-Workitems/, Meetings/, Infrastructure/ at root level. Each folder is a concern domain with different AI persona needs. +2. **Layered AI config** — .cursor/rules/ with 0XX-9XX classification + .claude/skills/ + _bmad/ all coexisting. Each layer has different ownership semantics. +3. **Cross-domain linkage** — Job interviews reference job descriptions. Work items trace to design blueprints. Tasks shard from stories. These relationships are the high-value rules to generate. +4. **Team boundaries** — Subfolders like frontend-team/, backend-team/ within work-items indicate scope isolation needs. diff --git a/_bmad-output/prd-ai-assisted-setup-2026-06-20/architecture.md b/_bmad-output/prd-ai-assisted-setup-2026-06-20/architecture.md new file mode 100644 index 0000000..c5be26d --- /dev/null +++ b/_bmad-output/prd-ai-assisted-setup-2026-06-20/architecture.md @@ -0,0 +1,686 @@ +--- +stepsCompleted: [1, 2, 3, 4, 5, 6] +inputDocuments: ['prd.md', 'addendum.md'] +workflowType: 'architecture' +project_name: 'AI-Assisted Complex Repo Auto-Setup' +date: '2026-06-20' +--- + +# Architecture Decision Document + +## Project Context Analysis + +### Requirements Overview + +**Functional Requirements:** +This system has 31 FRs across 8 feature groups. The architecture must support: +- Shell script entry point with flag parsing, target directory, auto-approval (FR-1 through FR-4, FR-25, FR-26) +- AI skill execution across 4 runtimes (FR-5 through FR-9) +- Preview and approval workflow (FR-10 through FR-12) +- Conflict detection and safety guarantees (FR-13 through FR-16) +- Multi-runtime output generation (FR-17 through FR-20) +- Manifest-based tracking for clean uninstall (FR-21, FR-22) +- Documentation updates (FR-23, FR-24) +- Test infrastructure: fixtures, shell runner, Python validator (FR-27 through FR-30) + +**Non-Functional Requirements:** +- Zero regression to existing setup.sh behavior +- Cross-platform (macOS, Windows via WSL/Git Bash, Linux) +- Minimal external dependencies: POSIX-compatible shell (sh), git, jq (for manifest JSON parsing). setup.sh verifies jq is available and prints install guidance if missing. +- AI runtimes are the execution engine — the system itself is passive files + +**Scale & Complexity:** +- Primary domain: File-based AI configuration system (not a software application) +- Complexity level: Medium — multiple interacting file artifacts but no runtime processes +- Components: Shell script (bootstrap), AI skill (logic), signal catalog (data), rule templates (generators), runtime adapters (translators), manifest (state) + +### Technical Constraints & Dependencies + +- Must work within agentic-os's existing file layout (`.agents/skills/` canonical path) +- AI runtimes have no shared execution model — each reads markdown differently +- Shell script must be POSIX-compatible (not bash-only) for maximum portability +- External dependency: `jq` required for `--remove` manifest parsing. setup.sh checks for jq on invocation of `--remove` and exits with guidance if missing. +- No Node.js, Python, or other runtime dependencies in the bootstrap path +- The AI skill is the only component with "intelligence" — everything else is data or scaffolding + +**Supported runtimes (v1 — canonical list):** + +| Runtime ID | Tool | Adapter File | Output Target | +|-----------|------|-------------|--------------| +| `claude` | Claude Code | adapters/claude.md | CLAUDE.md (or CLAUDE-agentic-os.md) | +| `cursor` | Cursor | adapters/cursor.md | .cursor/rules/NNN-agentic-os.mdc | +| `cline` | Cline | adapters/cline.md | .clinerules (or .clinerules-agentic-os) | +| `antigravity` | Antigravity | adapters/antigravity.md | AGENTS.md (managed block) | + +These are the only valid values for `--runtime`. Adding a new runtime requires: a new adapter file, a new entry in this table, and an update to `VALID_RUNTIMES` in setup.sh. + +### Cross-Cutting Concerns + +- **Safety:** Never modify user files except controlled append-only operations on `.gitignore` and AGENTS.md (managed blocks only); always preview before write +- **Portability:** Works across macOS/Linux/WSL without dependencies +- **Idempotency:** Running setup twice should not create duplicates +- **Privacy:** Generated configs may expose repo structure; gitignore by default +- **Coexistence:** Must detect and defer to existing frameworks (BMAD, etc.) + +--- + +## Starter Template Evaluation + +**Not applicable.** This is not a software application — it's a file-based system that extends an existing open-source project. No starter template, no build tools, no package managers. + +**Technology Stack:** +- **Shell:** POSIX sh for `setup.sh` (portability) +- **Markdown:** SKILL.md, signal catalog, rule templates (AI-readable) +- **JSON:** Manifest file for state tracking +- **YAML:** Cursor .mdc frontmatter generation + +--- + +## Core Architectural Decisions + +### Decision 1: System Architecture Model + +**Decision:** Passive file system with AI-runtime execution + +The system produces files that AI runtimes interpret. There is no server, no daemon, no build step. The "intelligence" lives entirely within the AI-installer SKILL.md — everything else is data the skill consumes. + +``` +┌─────────────────────────────────────────────────┐ +│ User's Repository │ +│ │ +│ setup.sh ──┐ │ +│ │ drops │ +│ ▼ │ +│ .agents/skills/agentic-os-setup/ │ +│ ├── SKILL.md (reasoning framework) │ +│ ├── catalog.md (signal catalog) │ +│ ├── templates/ (rule templates) │ +│ │ ├── persona-routing.md │ +│ │ ├── scope-isolation.md │ +│ │ ├── cross-reference.md │ +│ │ ├── naming-enforcement.md │ +│ │ └── quality-gates.md │ +│ ├── adapters/ (runtime adapters) │ +│ │ ├── claude.md │ +│ │ ├── cursor.md │ +│ │ ├── cline.md │ +│ │ └── antigravity.md │ +│ └── examples/ (calibration examples) │ +│ ├── simple-output.md │ +│ └── complex-output.md │ +│ │ +│ ← AI runtime reads SKILL.md and executes → │ +│ │ +│ Generated outputs: │ +│ ├── CLAUDE.md │ +│ ├── AGENTS.md (if complex tier) │ +│ ├── GOALS.md (if complex tier) │ +│ ├── .cursor/rules/NNN-agentic-os.mdc │ +│ ├── .clinerules │ +│ └── .agents/.agentic-os-manifest.json │ +└─────────────────────────────────────────────────┘ +``` + +**Rationale:** AI runtimes are the execution engine. The system provides instructions (SKILL.md) and data (catalog, templates). This is the same pattern agentic-os already uses for all its skills — consistency with existing architecture. + +### Decision 2: Shell Script Responsibilities (Minimal) + +**Decision:** `setup.sh` handles ONLY bootstrapping and teardown — never AI logic. + +**What setup.sh does:** +- Parse flags (`--ai`, `--runtime`, `--dry-run`, `--remove`, `--track`, `--target`, `--auto`, `--help`) +- Validate runtime flag values and dependency checks (jq for --remove) +- Resolve target directory (`--target ` or CWD) and `cd` into it for all operations +- **Bootstrap workspace infrastructure into target** (never overwrites existing files): + - Create `Tasks/`, `Knowledge/` directories + - Create `BACKLOG.md` (standard template) + - Copy `Workflows/` from agentic-os source + - Copy `.agents/skills/agentic-os-setup/` into target (or all skills if none exist) + - Ensure `.claude/skills/` bridge: symlink if absent, or copy `agentic-os-setup` into existing directory. Create `skills` symlink at root. + - Copy `.gitignore` from template (if none exists) + - Append skills reference to `CLAUDE.md` (if not already present) +- Write `.agents/.agentic-os-setup-context.json` with resolved flags (runtimes, dry_run, track, auto) +- Validate `--auto` requires explicit `--runtime` (cannot auto-detect in unattended mode) +- Print invocation instructions (`/agentic-os-setup` slash command for Claude Code, or "Run the agentic-os-setup skill" for other runtimes) +- Handle `--remove` (read manifest, delete tracked files) +- Add discoverability message to classic setup output + +**Source location:** The AI-installer skill files ship in-tree at `.agents/skills/agentic-os-setup/` as part of the agentic-os repo itself (same pattern as the existing 47 canonical skills). When running with `--target`, setup.sh copies the skill into the target repo so it's available locally. + +**Discoverability:** The SKILL.md includes YAML frontmatter (`name: agentic-os-setup`, `description: ...`) which enables Claude Code to discover it as a `/agentic-os-setup` slash command via `.claude/skills/`. Works whether `.claude/skills/` is a symlink (fresh repos) or a real directory (repos with existing skills already installed). This matches the pattern used by all other skills in the repo (e.g., `/bmad-prd`, `/bmad-brainstorming`). + +**What setup.sh does NOT do:** +- Scan repo structure (that's the AI's job) +- Generate config files (that's the AI's job) +- Detect complexity (that's the AI's job) +- Resolve conflicts (that's the AI's job) + +**Rationale:** Keeping the script minimal means: (1) no portability bugs in complex logic, (2) the AI can be updated independently of the script, (3) the smart behavior lives in one place (SKILL.md), not split between shell and markdown. + +### Decision 3: AI-Installer Skill Internal Architecture + +**Decision:** Single SKILL.md as orchestrator with modular supporting files. + +The SKILL.md is the entry point that the AI runtime reads. It references sub-files for specific concerns: + +``` +SKILL.md (orchestrator) + ├── reads: catalog.md (signal definitions) + ├── reads: templates/*.md (rule templates to fill) + ├── reads: adapters/*.md (how to format per-runtime) + └── reads: examples/*.md (calibration for output quality) +``` + +**SKILL.md sections:** +1. Mode detection (first-run vs dry-run vs re-run detection by checking manifest) +2. Scanning protocol (what to read, what to skip, privacy boundaries) +3. Classification logic (how to score complexity tiers) +4. Proposal generation (how to assemble output from templates + adapters) +5. Approval workflow (present diffs, wait for confirmation) +6. Write protocol (create files, update manifest, manage gitignore) + +**Rationale:** Modularity — the catalog can be updated without touching the orchestrator. Templates can be added for new rule types. Adapters can be added for new runtimes. But the single SKILL.md entry point means AI runtimes only need to read ONE file to start. + +### Decision 4: Signal Catalog Format + +**Decision:** Structured markdown with consistent entry format. + +```markdown +## Signal: .cursor/rules/ + +**Pattern:** Directory `.cursor/rules/` exists with `.mdc` files +**Indicates:** Existing Cursor AI configuration +**Complexity impact:** +1 tier signal +**Setup implications:** +- Scan existing rules for glob patterns (FR-13) +- Detect numbering convention (FR-14) +- Generate agentic-os rule in next available number slot +**Coexistence:** Additive only — never modify existing rules +``` + +Each signal entry has: Pattern, Indicates, Complexity impact, Setup implications, Coexistence behavior. + +**Rationale:** Structured enough for the AI to reason systematically, but markdown so it's human-readable and editable by contributors without tooling. + +### Decision 5: Rule Template Format + +**Decision:** Templates use placeholder syntax that the AI fills with detected values. + +```markdown +# Template: Persona Routing + +## Intent +Route AI persona/behavior based on which folder the user is editing in. + +## Inputs Required +- {domains}: List of detected concern domains with their folder paths +- {personas}: Mapping of domain → persona name and behavior description + +## Output Pattern (Cursor .mdc) +--- +description: Persona routing for agentic-os domains — {domain_name} +globs: {domain_path}/**/* +alwaysApply: true +--- +# {persona_name} Mode +{persona_behavioral_rules} + +## Output Pattern (CLAUDE.md section) +## Persona Routing +{for each domain} +- **{persona_name} Mode:** Triggered when editing `/{domain_path}/`. {persona_behavioral_rules} +{end for} + +## When to Use +- Complexity tier: Multi or Complex +- Detected: 2+ distinct concern domains with different intent +- NOT when: single-purpose repo or _bmad/ detected (defer persona to BMAD) +``` + +**Rationale:** Templates make the system predictable (contributors know what output looks like) while the AI fills in the specifics. The "When to Use" section prevents over-application. + +### Decision 6: Manifest Format and Location + +**Decision:** JSON manifest at `.agents/.agentic-os-manifest.json` + +```json +{ + "version": "1.0.0", + "created_at": "2026-06-20T15:30:00Z", + "complexity_tier": "multi", + "runtimes_targeted": ["claude", "cursor"], + "files": [ + { + "path": "CLAUDE.md", + "created_at": "2026-06-20T15:30:00Z", + "content_hash": "sha256:abc123..." + }, + { + "path": ".cursor/rules/900-agentic-os.mdc", + "created_at": "2026-06-20T15:30:00Z", + "content_hash": "sha256:def456..." + } + ], + "denied_relationships": [], + "detected_frameworks": ["bmad"] +} +``` + +**Location:** `.agents/` because that's already agentic-os's internal directory (gitignored by default in the template). + +**Version Migration Strategy:** The `version` field uses semver. Phase 2+ consumers MUST check version before processing: +- If manifest version < current expected version: run migration (add new fields with defaults, never delete old fields) +- If manifest version > current tool version: warn and proceed read-only (don't corrupt newer manifests) +- Phase 1 manifests will always be forward-readable because new phases ADD fields but never remove or rename existing ones (additive-only schema evolution) + +**Rationale:** JSON is parseable by both shell (jq) and AI runtimes. The content hash enables future re-run delta detection (Phase 2). Denied relationships prevent re-proposal. Additive-only schema evolution ensures Phase 1 installs survive Phase 2 upgrades without breakage. + +### Decision 7: Runtime Adapter Architecture + +**Decision:** Each adapter is a self-contained reference document describing how to format output for that runtime. + +The adapter does NOT contain code. It contains: +1. File path convention (where output goes) +2. Format specification (what valid output looks like) +3. Constraints (what this runtime can/cannot express) +4. Pre-existing file behavior (what to do if the target file already exists) +5. Examples (concrete output samples) + +The AI reads the adapter and uses it as a formatting guide when generating output from templates. + +**Pre-existing file behavior per runtime:** + +| Runtime | Target file | If file exists already | +|---------|------------|----------------------| +| Claude Code | CLAUDE.md | Create `CLAUDE-agentic-os.md` as additive companion file. Reference it from proposal. Never modify existing CLAUDE.md. | +| Cursor | .cursor/rules/NNN-agentic-os.mdc | Always a new file (numbered). No conflict — glob collision detection handles overlap. | +| Cline | .clinerules | Create `.clinerules-agentic-os` as additive companion file. Never modify existing .clinerules. | +| Antigravity | AGENTS.md | Extend with managed block (append below user content). | + +**Antigravity-specific behavior:** Antigravity uses AGENTS.md as its primary instruction file — the same file agentic-os already generates in classic mode and that users may have hand-written. The Antigravity adapter therefore specifies **extend semantics**: user content stays intact at the top, agentic-os appends a managed block below. This is the only runtime where the AI modifies an existing user file (append-only, never changes existing content). + +``` +AGENTS.md (Antigravity extend pattern): +┌─────────────────────────────────────────────────────────────────┐ +│ [User's original content] │ ← never touched +│ ... │ +├─────────────────────────────────────────────────────────────────┤ +│ │ ← managed block starts +│ ## Agentic-OS Generated Rules │ +│ ### Persona Routing │ +│ ### Scope Isolation │ +│ ### Quality Gates │ +│ │ ← managed block ends +└─────────────────────────────────────────────────────────────────┘ +``` + +**Canonical managed block marker format** (used everywhere — .gitignore comment block uses equivalent `# === AGENTIC-OS GENERATED ===` for gitignore syntax): +- Start: `` +- End: `` +- Hash covers the content between markers (enables Phase 2 change detection) + +**Rationale:** Adapters as reference docs means: (1) new runtimes can be supported by adding one file, (2) no code changes needed, (3) the AI handles the translation logic — we just teach it the target format. The Antigravity extend pattern prevents the "existing AGENTS.md gets replaced" failure mode identified in UJ-4. + +### Decision 8: Conflict Detection Strategy + +**Decision:** Pre-write scan with abort semantics. + +Before writing ANY file, the AI must: +1. Check if the target path already exists (abort if user file, unless extending) +2. For .cursor/rules: scan ALL existing .mdc files for glob patterns that would overlap (UJ-1, UJ-2) +3. For CLAUDE.md: check if one exists already; if so, propose additions only (UJ-3) +4. For AGENTS.md: check if one exists already; if so, propose extension via managed block — if existing content has conflicting persona definitions, propose reconciliation options (UJ-4) + +On conflict: report the collision clearly, propose alternatives, and wait for user decision. Never write conflicting content. + +**Rationale:** "Ask forgiveness" is wrong for config files that affect daily work. One silent glob collision = hours of debugging "why is my AI behaving differently." Prevention over recovery. + +### Decision 9: Gitignore Management + +**Decision:** Append-only block with clear delimiters. + +```gitignore +# === AGENTIC-OS GENERATED (do not edit this block) === +CLAUDE.md +.cursor/rules/900-agentic-os.mdc +.clinerules +.agents/.agentic-os-manifest.json +# === END AGENTIC-OS GENERATED === +``` + +The `--remove` command strips this exact block. The `--track` flag skips gitignore entirely. + +**Rationale:** Delimited block enables clean removal without parsing complex gitignore files. The comment makes it obvious to humans what's managed. + +--- + +## Implementation Patterns & Consistency Rules + +### File Naming Patterns + +| Artifact Type | Convention | Example | +|--------------|------------|---------| +| Skill files | UPPERCASE.md or lowercase-kebab.md | SKILL.md, catalog.md | +| Template files | lowercase-kebab.md | persona-routing.md | +| Adapter files | lowercase-runtime-name.md | claude.md, cursor.md | +| Example files | lowercase-purpose.md | simple-output.md | +| Generated configs | Follow target runtime convention | .cursor/rules/NNN-*.mdc | +| Manifest | dot-prefixed JSON | .agentic-os-manifest.json | + +### Markdown Authoring Patterns for AI-Readable Content + +**Structure pattern for all skill sub-files:** +```markdown +# {Title} + +## Purpose +One sentence explaining what this file is for. + +## {Main Content Sections} +... + +## Usage Context +When this file is relevant and how the AI should use it. +``` + +**Placeholder syntax:** `{variable_name}` for single values, `{for each item}...{end for}` for iteration. These are not executed — they're instructions to the AI about what to substitute. + +### Shell Script Patterns + +**Flag parsing:** Use `getopts` or manual case parsing (POSIX compatible, no bashisms). + +**Exit codes:** +- 0: Success +- 1: Invalid flags/arguments +- 2: Missing dependencies +- 3: Conflict detected (--remove found modified files) + +**Output format:** Minimal, actionable. One instruction per line. Color only via tput (portable). + +### Generated Output Patterns + +**Managed block markers (for future Phase 2 re-run):** +```markdown + +{generated content} + +``` + +Even in Phase 1 (no re-run), include these markers so Phase 2 can detect them later without regenerating all files. + +**Cursor .mdc generation rules:** +- YAML frontmatter is required (description, globs) +- `alwaysApply: true` only when the rule genuinely applies to all matched files +- Globs must be specific (never `*` alone for agentic-os rules) +- Description must be human-readable and explain intent + +--- + +## Project Structure & Boundaries + +### Complete Directory Structure (what this feature adds to agentic-os) + +``` +agentic-os/ (existing repo root) +├── setup.sh (MODIFIED: add --ai, --runtime, --dry-run, --remove, --track, --target, --auto flags) +├── pytest.ini (NEW: pytest configuration — test paths, JUnit XML output) +├── .agents/ +│ └── skills/ +│ └── agentic-os-setup/ (NEW: AI-installer skill directory) +│ ├── SKILL.md (orchestrator — entry point for AI execution) +│ ├── catalog.md (signal catalog — known patterns + meanings) +│ ├── agents/ +│ │ └── openai.yaml (Agent Skills open standard metadata) +│ ├── templates/ +│ │ ├── persona-routing.md +│ │ ├── scope-isolation.md +│ │ ├── cross-reference.md +│ │ ├── naming-enforcement.md +│ │ └── quality-gates.md +│ ├── adapters/ +│ │ ├── claude.md +│ │ ├── cursor.md +│ │ ├── cline.md +│ │ └── antigravity.md +│ └── examples/ +│ ├── simple-output.md +│ └── complex-output.md +├── examples/ (NEW: test repo fixtures) +│ ├── uj-1-node-monorepo/ +│ ├── uj-2-architect-monorepo/ +│ ├── uj-3-flask-simple/ +│ └── uj-4-rust-antigravity/ +├── tests/ (NEW: automated test suite) +│ ├── test_setup.sh (POSIX sh — flag parsing tests) +│ ├── test_content.py (pytest — content validation) +│ ├── conftest.py (pytest hook — plaintext report generation) +│ └── results/ (gitignored — test output) +│ ├── shell/report.txt +│ └── python/report.xml, report.txt +└── (no other root-level changes) +``` + +### What Gets Generated (in user's repo, not in agentic-os source) + +``` +user-repo/ (after AI-installer executes) +├── CLAUDE.md (if --runtime includes claude) +├── AGENTS.md (if complexity ≥ Multi) +├── GOALS.md (if complexity = Complex) +├── .cursor/ +│ └── rules/ +│ └── NNN-agentic-os.mdc (if --runtime includes cursor) +├── .clinerules (if --runtime includes cline) +├── .agents/ +│ └── .agentic-os-manifest.json (always — tracks what was generated) +└── .gitignore (appended with managed block, unless --track) +``` + +### Boundary Definitions + +**Bootstrap boundary (setup.sh):** +- Input: CLI flags +- Output: Skill presence verified (ships in-tree), setup context written to `.agents/.agentic-os-setup-context.json`, terminal instruction printed +- Context bridge: setup.sh writes `{ "runtimes": [...], "dry_run": bool, "track": bool, "auto": bool }` so the AI skill knows what flags were passed +- Target resolution: `--target ` changes working directory before all operations (default: CWD). setup.sh copies the agentic-os-setup skill and workspace infrastructure into the target before writing the context bridge, so all files are local when the AI runs. +- Does NOT cross into: repo scanning, config generation, AI interaction + +**AI execution boundary (SKILL.md):** +- Input: Entire repository filesystem (read-only scan) — all infrastructure is already local (setup.sh copied it) +- Responsibilities: Create/update AGENTS.md, infer GOALS.md, generate runtime-specific config (CLAUDE-agentic-os.md, etc.) +- Data sources: catalog.md, templates/, adapters/, examples/ (all at `.agents/skills/agentic-os-setup/`) +- Output: Proposed file contents (presented as diffs) +- Write authority: Only after explicit user approval (or auto-mode) +- State: Reads/writes manifest.json (tracks all AI-generated files) + +**Adapter boundary:** +- Input: Structured intent (domain list, personas, relationships) +- Output: Runtime-specific formatted content +- Does NOT cross into: detection logic, approval workflow + +**Manifest boundary:** +- Created by: AI-installer (write) +- Read by: setup.sh --remove (for cleanup), AI-installer re-run detection (Phase 2) +- Never read by: the generated configs themselves + +--- + +## Validation Checklist + +### Architectural Coherence + +- [x] Single source of truth: SKILL.md is the only file with execution logic +- [x] Separation of concerns: script (bootstrap) / skill (logic) / catalog (data) / templates (patterns) / adapters (format) +- [x] No circular dependencies between components +- [x] Each component can be updated independently +- [x] New runtimes = add one adapter file (no orchestrator changes) +- [x] New rule types = add one template file (no orchestrator changes) +- [x] New signals = add entry to catalog (no structural changes) + +### PRD Requirement Coverage + +| FR | Covered By | Architecture Component | +|----|-----------|----------------------| +| FR-1 (flags) | setup.sh | Bootstrap boundary | +| FR-2 (runtime targeting) | setup.sh + SKILL.md | Flag parsing + adapter selection | +| FR-3 (uninstall) | setup.sh + manifest | Manifest read + file deletion | +| FR-4 (discoverability) | setup.sh | Classic output modification | +| FR-5 (scanning) | SKILL.md + catalog.md | Scanning protocol + signal matching | +| FR-6 (classification) | SKILL.md + catalog.md | Classification logic | +| FR-7 (proposal) | SKILL.md + templates + adapters | Template filling + adapter formatting | +| FR-8 (relationships) | SKILL.md | Relationship discovery protocol | +| FR-9 (signal catalog) | catalog.md | Standalone data file | +| FR-10 (diff preview) | SKILL.md | Approval workflow section | +| FR-11 (dry-run) | SKILL.md | Mode detection section | +| FR-12 (approval gate) | SKILL.md | Write protocol section | +| FR-13 (glob collision) | SKILL.md + adapters/cursor.md | Conflict detection + cursor-specific rules | +| FR-14 (numbering) | SKILL.md + adapters/cursor.md | Cursor adapter constraint | +| FR-15 (non-destructive) | SKILL.md | Core invariant in scanning + write protocol; .gitignore and AGENTS.md allow append-only managed blocks | +| FR-16 (framework coexistence) | SKILL.md + catalog.md | Signal for _bmad/ with "defer" behavior | +| FR-17 (Claude adapter) | adapters/claude.md | Create new CLAUDE.md | +| FR-18 (Cursor adapter) | adapters/cursor.md | Create new .mdc with glob/numbering logic | +| FR-19 (Cline adapter) | adapters/cline.md | Create new .clinerules | +| FR-20 (Antigravity adapter) | adapters/antigravity.md | Extend existing AGENTS.md with managed block (UJ-4) | +| FR-21 (manifest) | SKILL.md + manifest format | Write protocol + JSON schema | +| FR-22 (gitignore) | SKILL.md + setup.sh | Write protocol + --track flag | +| FR-23 (README update) | README.md | Document --ai path, update architecture diagram, add runtimes | +| FR-24 (CONTRIBUTING.md) | CONTRIBUTING.md | Guide for adding signals, templates, adapters; testing protocol | +| FR-25 (target directory) | setup.sh | --target flag, resolve dir before all operations | +| FR-26 (auto-approval) | setup.sh + SKILL.md | --auto flag, context bridge `auto` field, skip approval gate | +| FR-27 (test fixtures) | examples/ | 4 UJ-based directory structures | +| FR-28 (shell test runner) | tests/test_setup.sh | POSIX sh flag/routing tests | +| FR-29 (Python validator) | tests/test_content.py | pytest structural validation | +| FR-30 (results gitignored) | .gitignore | tests/results/ excluded | +| FR-31 (workspace bootstrapping) | setup.sh + SKILL.md | setup.sh copies infrastructure; AI creates AGENTS.md, infers GOALS.md | + +### Risk Mitigations Confirmed + +| Risk | Mitigation in Architecture | +|------|---------------------------| +| Config breaks existing workflows | Conflict detection in SKILL.md is mandatory pre-write step | +| Complexity wall (too many files) | Tier-gated output defined in SKILL.md classification logic | +| User edit corruption on re-run | Managed block markers included from Phase 1; manifest tracks hashes | +| Privacy/security exposure | Manifest location in .agents/ (gitignored); generated files gitignored by default | + +--- + +## Pull Request + +The PR document for this feature is at `pull-request.md` in this directory. It serves as the template for opening the upstream PR to itseffi/agentic-os and documents the BMad Method planning process, key design decisions, testing instructions, and scope boundaries. + +--- + +## Test Infrastructure Architecture + +### Decision 10: Test Repo Fixtures + +**Decision:** Real directory structures in `examples/` mimic each UJ's repo layout. + +``` +examples/ +├── uj-1-node-monorepo/ (UJ-1: Alex's Node.js monorepo with Cursor rules) +│ ├── package.json (workspaces: ["packages/*"]) +│ ├── .cursor/rules/ +│ │ ├── 002-dates.mdc +│ │ ├── 003-eslint.mdc +│ │ └── 005-api.mdc +│ ├── packages/ +│ │ ├── api/package.json +│ │ └── web/package.json +│ ├── src/ +│ └── tests/ +├── uj-2-architect-monorepo/ (UJ-2: Sam's complex documentation monorepo) +│ ├── Designs/ +│ ├── Operations/ +│ │ ├── job-descriptions/ +│ │ └── job-interviews/ +│ ├── Team-Workitems/ +│ ├── Infrastructure/ +│ ├── _bmad/ +│ ├── .cursor/rules/ (10 files, 800-band) +│ └── AGENTS.md +├── uj-3-flask-simple/ (UJ-3: Jordan's simple Flask project) +│ ├── src/ +│ │ └── app.py +│ ├── tests/ +│ ├── requirements.txt +│ └── README.md +└── uj-4-rust-antigravity/ (UJ-4: Riley's Rust workspace) + ├── Cargo.toml ([workspace] with members) + ├── api/ + │ └── Cargo.toml + ├── core/ + │ └── Cargo.toml + ├── shared/ + │ └── Cargo.toml + └── AGENTS.md +``` + +**Rationale:** Real structures (not mocks or descriptions) enable `setup.sh --ai --target examples/uj-X` to exercise the full flow. Each fixture represents a distinct complexity tier and runtime scenario. + +### Decision 11: Dual Test Runner Strategy + +**Decision:** Shell tests for setup.sh behavior + Python tests for generated content validation. + +| Layer | Runner | What It Tests | Results | +|-------|--------|---------------|---------| +| CLI behavior | `tests/test_setup.sh` (POSIX sh) | Flag parsing, routing, error cases, --remove | `tests/results/shell/report.txt` (plaintext) | +| Content quality | `tests/test_content.py` (pytest) | Manifest schema, .mdc validity, glob rules, managed blocks | `tests/results/python/report.xml` (JUnit XML) + `tests/results/python/report.txt` (plaintext) | + +**Configuration files:** +- `pytest.ini` — Configures test paths and `--junitxml` output +- `tests/conftest.py` — Generates plaintext report via `pytest_sessionfinish` hook + +**5 test scenarios:** +1. Simple project (uj-3 fixture) — verify simple tier, minimal output +2. Complex project (uj-2 fixture) — verify complex tier, BMAD deferral +3. Collision detection (uj-1 fixture with overlapping glob) — verify abort on conflict +4. Clean uninstall (any fixture post-setup) — verify zero leftovers +5. Auto-mode (uj-3 fixture + --auto --runtime claude) — verify no-pause write + +**Results gitignored:** `tests/results/` in `.gitignore`. + +**Rationale:** Shell tests validate the bootstrap layer (no Python dependency for core script). Python tests validate structural correctness of generated artifacts (JSON schema, YAML parsing, regex matching for markers). Both are needed because setup.sh is POSIX sh but generated content needs structured validation. + +--- + +## Implementation Sequence + +### Phase 1 Implementation Order + +1. **setup.sh modifications** — Add flag parsing, --remove logic, discoverability message +2. **SKILL.md orchestrator** — Core reasoning framework, mode detection, scanning protocol, classification, proposal, approval, write protocol +3. **catalog.md** — Initial signal catalog (15-20 signals covering common patterns) +4. **adapters/claude.md** — Claude Code output formatting reference +5. **adapters/cursor.md** — Cursor .mdc output formatting reference (most complex due to glob handling) +6. **adapters/cline.md** — Cline output formatting reference +7. **adapters/antigravity.md** — Antigravity AGENTS.md formatting reference +8. **templates/persona-routing.md** — First rule template +9. **templates/scope-isolation.md** — Second rule template +10. **templates/cross-reference.md** — Third rule template +11. **templates/naming-enforcement.md** — Fourth rule template +12. **templates/quality-gates.md** — Fifth rule template +13. **examples/simple-output.md** — Calibration: what tier 1-2 output looks like +14. **examples/complex-output.md** — Calibration: what tier 3-4 output looks like +15. **Testing** — Manual testing across runtimes with sample repos + +### Dependencies Between Components + +``` +setup.sh ─── independent (no deps) +SKILL.md ─── depends on: catalog.md, templates/*, adapters/*, examples/* +catalog.md ─── independent (pure data, follows interface contract below) +templates/* ─── independent (pure patterns, follows interface contract below) +adapters/* ─── independent (pure format specs, follows interface contract below) +examples/* ─── depends on: templates + adapters (shows their combined output) +``` + +**Parallel development strategy:** Leaf components (catalog, templates, adapters) can be developed in parallel with SKILL.md IF they follow these interface contracts: + +| Component | Contract (structure SKILL.md expects) | +|-----------|--------------------------------------| +| catalog.md | Each signal: `## Signal: ` with subsections: Pattern, Indicates, Complexity impact, Setup implications, Coexistence | +| templates/*.md | Each template: `# Template: ` with subsections: Intent, Inputs Required (`{placeholder}`), Output Pattern (per runtime), When to Use | +| adapters/*.md | Each adapter: File path convention, Format specification, Constraints, Pre-existing file behavior, Examples (2+) | + +**Integration point:** SKILL.md is written last (or iteratively) as it consumes all leaf components. Examples are written after both templates and adapters since they demonstrate combined output. The claimed parallelism is real for leaf files but SKILL.md itself is the integration test — it cannot be finalized until leaf files stabilize. diff --git a/_bmad-output/prd-ai-assisted-setup-2026-06-20/epics.md b/_bmad-output/prd-ai-assisted-setup-2026-06-20/epics.md new file mode 100644 index 0000000..afc0c97 --- /dev/null +++ b/_bmad-output/prd-ai-assisted-setup-2026-06-20/epics.md @@ -0,0 +1,705 @@ +--- +stepsCompleted: [1, 2, 3] +inputDocuments: ['prd.md', 'architecture.md', 'addendum.md'] +--- + +# AI-Assisted Complex Repo Auto-Setup - Epic Breakdown + +## Overview + +This document provides the complete epic and story breakdown for the AI-Assisted Complex Repo Auto-Setup feature, decomposing the PRD and Architecture into implementable stories. This is a file-based system (markdown, shell scripts) — stories produce files, not code. + +**Delivery:** The PR template for this feature is at `pull-request.md`. When all epics are complete, use that document as the basis for opening the upstream PR to itseffi/agentic-os. + +## Requirements Inventory + +### Functional Requirements + +- FR-1: Flag-based mode selection (`setup.sh --ai` enables advanced, no flags = classic unchanged) +- FR-2: Runtime targeting (`--runtime `, v1 valid values: `claude`, `cursor`, `cline`, `antigravity` — adding a runtime requires a new adapter file + setup.sh VALID_RUNTIMES update) +- FR-3: Clean uninstall (`setup.sh --remove` deletes only agentic-os generated files) +- FR-4: Discoverability (classic setup completion message includes `--ai` prompt) +- FR-5: Repo structure scanning (AI reads filesystem, builds structural profile) +- FR-6: Complexity classification (4 tiers: zero, simple, multi, complex) +- FR-7: Configuration proposal (output proportional to tier, tailored to repo) +- FR-8: Relationship discovery (manifest-declared trusted, AI-inferred requires confirmation) +- FR-9: Signal catalog (structured list of known patterns and meanings) +- FR-10: Unified diff preview (all proposed changes shown as diffs before write) +- FR-11: Dry-run mode (full analysis, no writes to disk) +- FR-12: Approval gate (explicit user confirmation before writing) +- FR-13: Glob collision detection (scan existing .mdc files for pattern overlap) +- FR-14: Existing rule numbering respect (append to next available in appropriate band) +- FR-15: Non-destructive file policy (never modify or delete user files) +- FR-16: Framework coexistence detection (defer persona ownership if _bmad/ detected) +- FR-17: Claude Code adapter (generates CLAUDE.md with routing and rules) +- FR-18: Cursor adapter (generates .cursor/rules/NNN-agentic-os.mdc with proper frontmatter) +- FR-19: Cline adapter (generates .clinerules) +- FR-20: Antigravity adapter (extends existing AGENTS.md with managed block) +- FR-21: Manifest tracking (JSON at .agents/.agentic-os-manifest.json) +- FR-22: Gitignore management (append managed block, unless --track) +- FR-23: README update (document --ai path, architecture diagram, runtimes) +- FR-24: CONTRIBUTING.md (guide for adding signals, templates, adapters) +- FR-25: Target directory (`--target `, default CWD) +- FR-26: Auto-approval mode (`--auto` requires explicit `--runtime`, shows preview then writes) +- FR-27: Test repo fixtures (real directory structures for UJ-1 through UJ-4) +- FR-28: Shell test runner (POSIX sh, flag parsing validation) +- FR-29: Python content validator (pytest, structural validation of generated content) +- FR-30: Test results gitignored (tests/results/ excluded from tracking) +- FR-31: Workspace bootstrapping (copy agentic-os infrastructure to target, auto-generate GOALS.md from repo analysis) + +### NonFunctional Requirements + +- NFR-1: Zero regression to existing setup.sh behavior +- NFR-2: Cross-platform (macOS, Linux, Windows via WSL/Git Bash) +- NFR-3: POSIX sh compatible (no bashisms in setup.sh) +- NFR-4: Minimal external dependencies (git, jq); setup.sh verifies jq availability before --remove operations +- NFR-5: Privacy-respecting scan (don't read file contents beyond configs/manifests) +- NFR-6: Generated files gitignored by default (security-first) +- NFR-7: Test results isolated (tests/results/ gitignored, no pollution of tracked files) + +### Additional Requirements + +- AR-1: Managed block markers included from Phase 1 (for future Phase 2 re-run compatibility) +- AR-2: Signal catalog must be contributor-friendly (structured markdown, not code) +- AR-3: Rule templates use placeholder syntax (predictable, AI fills specifics) +- AR-4: Adapters are reference docs (one file per runtime, no code) +- AR-5: Manifest uses JSON for shell-parseability (jq) and AI-readability +- AR-6: SKILL.md is single entry point (AI reads one file to start) + +### UX Design Requirements + +N/A — no UI component in this system. + +### FR Coverage Map + +- FR-1, FR-2, FR-3, FR-4, FR-25, FR-26: Epic 1 (Bootstrap & CLI) +- FR-5, FR-6, FR-7, FR-8, FR-9, FR-31: Epic 2 (AI-Installer Skill Core) +- FR-10, FR-11, FR-12: Epic 3 (Preview & Approval) +- FR-13, FR-14, FR-15, FR-16: Epic 3 (Preview & Approval — safety checks) +- FR-17, FR-18, FR-19, FR-20: Epic 4 (Runtime Adapters) +- FR-21, FR-22: Epic 5 (Manifest & Cleanup) +- FR-23, FR-24: Epic 6 (Documentation) +- FR-27, FR-28, FR-29, FR-30: Epic 7 (Test Infrastructure) + +## Epic List + +### Epic 1: Bootstrap Entry Point +Users can invoke the AI-assisted setup via shell script flags, target any directory, run in auto-approval mode, cleanly remove agentic-os, and discover the feature through the classic setup flow. +**FRs covered:** FR-1, FR-2, FR-3, FR-4, FR-25, FR-26 + +### Epic 2: AI-Installer Skill Core +Users can have their repo intelligently analyzed — structure scanned, complexity classified, relationships discovered, and configuration proposed — all by invoking a single AI skill. +**FRs covered:** FR-5, FR-6, FR-7, FR-8, FR-9 + +### Epic 3: Preview, Safety & Approval +Users see exactly what will change (as diffs), are protected from conflicts with existing configs, and must explicitly approve before anything is written. +**FRs covered:** FR-10, FR-11, FR-12, FR-13, FR-14, FR-15, FR-16 + +### Epic 4: Runtime Adapters +Users get semantically equivalent configuration output in the native format of their chosen AI tools — Claude Code, Cursor, Cline, or Antigravity. +**FRs covered:** FR-17, FR-18, FR-19, FR-20 + +### Epic 5: Manifest & State Management +Users can track what was generated, cleanly uninstall, and have generated files gitignored by default for security. +**FRs covered:** FR-21, FR-22 + +### Epic 6: Documentation & Contributing +Users and contributors can understand the feature, its usage, and how to extend it through updated README and new CONTRIBUTING.md. +**FRs covered:** FR-23, FR-24 + +### Epic 7: Test Infrastructure +Developers and contributors can validate setup.sh behavior and generated content quality through automated tests running against real repo fixtures. +**FRs covered:** FR-27, FR-28, FR-29, FR-30 + +--- + +## Epic 1: Bootstrap Entry Point + +Users can invoke the AI-assisted setup via shell script flags, cleanly remove agentic-os, and discover the feature through the classic setup flow. + +### Story 1.1: Add --ai flag and argument parsing to setup.sh + +As a developer, +I want to run `setup.sh --ai` to enable AI-assisted setup, +So that I can get intelligent configuration without affecting the classic flow. + +**Acceptance Criteria:** + +**Given** a user runs `setup.sh` without any flags +**When** the script executes +**Then** behavior is 100% identical to current implementation (regression-safe) +**And** no AI-related files are created or referenced + +**Given** a user runs `setup.sh --help` +**When** the script executes +**Then** it prints usage information listing all available flags (--ai, --runtime, --dry-run, --remove, --track, --target, --auto, --help) +**And** exits without executing setup + +**Given** a user runs `setup.sh --ai` +**When** the script executes +**Then** it verifies jq is installed (required for --remove); if missing, prints install guidance and continues (jq only blocks --remove, not --ai) +**And** the AI-installer skill directory `.agents/skills/agentic-os-setup/` is verified to exist (ships in-tree) +**And** `.agents/.agentic-os-setup-context.json` is written with resolved flags (runtimes, dry_run, track) +**And** the script prints clear invocation instructions for the user's AI tool +**And** the classic questionnaire is NOT executed + +### Story 1.2: Add --runtime flag for targeting specific AI tools + +As a developer, +I want to specify which AI runtimes to configure via `--runtime claude,cursor`, +So that I only get configuration for tools I actually use. + +**Acceptance Criteria:** + +**Given** a user runs `setup.sh --ai --runtime claude,cursor` +**When** the script validates the flag +**Then** only `claude` and `cursor` are passed as targeting context to the AI skill +**And** invalid runtime names produce a clear error listing valid options (claude, cursor, cline, antigravity) + +**Given** a user runs `setup.sh --ai` without `--runtime` +**When** the script executes +**Then** all runtimes are targeted by default (the AI skill will detect which are present) + +### Story 1.3: Add --remove flag for clean uninstall + +As a developer, +I want to run `setup.sh --remove` to cleanly undo agentic-os setup, +So that I can safely try it without commitment anxiety. + +**Acceptance Criteria:** + +**Given** a user runs `setup.sh --remove` and jq is not installed +**When** the script checks dependencies +**Then** it prints "Error: jq is required for --remove. Install: brew install jq (macOS) or apt install jq (Linux)" and exits with code 2 + +**Given** a user runs `setup.sh --remove` and a manifest exists at `.agents/.agentic-os-manifest.json` +**When** the script reads the manifest (using jq) +**Then** every file listed in the manifest is deleted +**And** the gitignore managed block (`# === AGENTIC-OS GENERATED ===`) is removed +**And** the setup context file (`.agents/.agentic-os-setup-context.json`) is deleted +**And** the manifest file itself is deleted +**And** a summary of deleted files is printed + +**Given** a user runs `setup.sh --remove` and no manifest exists +**When** the script checks for the manifest +**Then** it prints "No agentic-os installation found" and exits cleanly + +**Given** setup.sh --remove runs +**When** checking each file in the manifest +**Then** user's original files (not in manifest) are NEVER deleted or modified + +### Story 1.5: Add --target flag for directory targeting + +As a developer, +I want to run `setup.sh --ai --target ./my-project` to configure a different repo, +So that I can set up agentic-os without being inside the target directory. + +**Acceptance Criteria:** + +**Given** a user runs `setup.sh --ai --target ./some-project` +**When** the script executes +**Then** workspace infrastructure is bootstrapped into `./some-project` (skills, workflows, dirs, symlinks) +**And** the context bridge is written at `./some-project/.agents/.agentic-os-setup-context.json` +**And** the AI skill is locally available at `./some-project/.agents/skills/agentic-os-setup/SKILL.md` +**And** CLAUDE.md in the target has a skills reference section appended (if not already present) + +**Given** a user runs `setup.sh --ai --target ./nonexistent` +**When** the script validates the target +**Then** it prints "Error: target directory does not exist: ./nonexistent" and exits with code 1 + +**Given** a user runs `setup.sh --ai` without `--target` +**When** the script executes +**Then** CWD is used as the target (unchanged default behavior) + +**Given** a user runs `setup.sh --remove --target ./some-project` +**When** the script executes removal +**Then** the manifest at `./some-project/.agents/.agentic-os-manifest.json` is read and files are deleted relative to `./some-project` + +### Story 1.6: Add --auto flag for unattended approval + +As a developer running setup in a CI/automation context, +I want `setup.sh --ai --auto --runtime claude` to run without interactive approval, +So that setup can complete unattended while still showing what was generated. + +**Acceptance Criteria:** + +**Given** a user runs `setup.sh --ai --auto --runtime claude` +**When** the script validates flags +**Then** the context bridge contains `"auto": true` +**And** the AI skill reads `auto: true` and skips the approval gate (shows preview then writes immediately) + +**Given** a user runs `setup.sh --ai --auto` WITHOUT `--runtime` +**When** the script validates flags +**Then** it prints "Error: --auto requires explicit --runtime (cannot auto-detect in unattended mode)" and exits with code 1 + +**Given** the AI skill runs in auto mode and detects a glob collision +**When** reaching the conflict detection step +**Then** it fails with a non-zero exit (does NOT silently overwrite) and prints the conflict report + +**Given** a user passes both `--auto` and `--dry-run` +**When** the AI skill executes +**Then** diffs are shown but nothing is written (dry-run takes precedence) + +### Story 1.4: Add discoverability message to classic setup + +As a first-time user who ran the classic setup, +I want to see a hint about the --ai option, +So that I know a smarter setup path exists. + +**Acceptance Criteria:** + +**Given** a user completes the classic `setup.sh` questionnaire +**When** setup finishes successfully +**Then** the final output includes: "Want AI-powered setup? Run: setup.sh --ai" +**And** it's a single line (not a wall of text) +**And** it appears after the success message, not before + +--- + +## Epic 2: AI-Installer Skill Core + +Users can have their repo intelligently analyzed — structure scanned, complexity classified, relationships discovered, and configuration proposed — by invoking a single AI skill. + +### Story 2.5: Define workspace bootstrapping protocol in SKILL.md + +As a user running AI-assisted setup against their existing project, +I want agentic-os to set up the full workspace infrastructure (directories, AGENTS.md, skills, workflows, GOALS.md) automatically, +So that my repo is immediately usable as a personal OS without running the classic questionnaire. + +**Acceptance Criteria:** + +**Given** the AI skill runs against a target repo that has no agentic-os infrastructure +**When** the bootstrap phase executes +**Then** it creates: Tasks/, Knowledge/, BACKLOG.md, copies AGENTS.md, Workflows/, .agents/skills/ from the agentic-os source +**And** ensures `.claude/skills/agentic-os-setup/` exists (symlink bridge if fresh, or copy into existing directory) +**And** creates .gitignore from template if none exists +**And** creates CLAUDE.md with `@AGENTS.md` if none exists +**And** all created files are tracked in the manifest + +**Given** the AI skill scans the target repo for GOALS.md inference +**When** generating GOALS.md +**Then** it infers: role (from README/package.json/git config), vision (from project scope), quarterly objectives (from recent activity), priorities (from most-active areas) +**And** marks inferred content with `[AI-inferred — refine as needed]` +**And** leaves empty fields with `` + +**Given** the target repo already has some agentic-os artifacts (e.g., AGENTS.md exists) +**When** the AI encounters existing files +**Then** it skips or extends them (never overwrites) +**And** notes what was skipped in the proposal summary + +**Given** setup.sh has already bootstrapped the workspace +**When** the AI skill runs +**Then** all supporting files (catalog.md, templates/, adapters/, examples/) are at `.agents/skills/agentic-os-setup/` locally — no external path resolution needed + +--- + +### Story 2.1: Create SKILL.md orchestrator + +As a user invoking the setup skill in their AI tool, +I want a single instruction file that guides the AI through the entire setup process, +So that any supported runtime can execute the same intelligent workflow. + +**Acceptance Criteria:** + +**Given** the file `.agents/skills/agentic-os-setup/SKILL.md` exists +**When** an AI runtime reads it +**Then** it contains: mode detection, scanning protocol, classification logic, proposal generation, approval workflow, and write protocol sections +**And** it references catalog.md, templates/*, adapters/*, and examples/* for supporting data +**And** the skill includes `agents/openai.yaml` with name, description, version, and invocation fields (Agent Skills open standard compliance) +**And** the SKILL.md has YAML frontmatter with `name: agentic-os-setup` and `description:` fields enabling Claude Code slash-command discovery (`/agentic-os-setup`) via `.claude/skills/` (works as symlink or directory) +**And** the scanning protocol specifies what to read (directory structure, config files, manifests) and what to skip (file contents, binary files) +**And** the write protocol enforces: never write without approval, never modify user files (except append-only managed blocks on .gitignore and AGENTS.md) +**And** the write protocol defines the managed block format specification: marker syntax (``), hash algorithm (SHA-256 of block content), start/end delimiter rules, and behavior when user edits are detected inside a managed block (warn and skip overwrite) + +### Story 2.2: Create signal catalog + +As an AI executing the setup skill, +I want a structured catalog of known filesystem patterns and their meanings, +So that I can anchor my detection and avoid hallucinating repo structure. + +**Acceptance Criteria:** + +**Given** the file `.agents/skills/agentic-os-setup/catalog.md` exists +**When** an AI reads it during scanning +**Then** it contains at minimum 15 signal entries covering common patterns +**And** each entry has: Pattern, Indicates, Complexity impact, Setup implications, Coexistence behavior +**And** signals include: `.cursor/rules/`, `.claude/`, `.clinerules`, `_bmad/`, `package.json`, `pyproject.toml`, `Cargo.toml`, `terraform/`, `docs/`, `src/`, `.github/`, `docker-compose.yml`, `Makefile`, `AGENTS.md`, `go.mod` + +**Given** a repo contains a pattern not in the catalog +**When** the AI encounters it +**Then** the catalog does not prevent the AI from reasoning about novel patterns (it's a reference, not a hard gate) + +### Story 2.3: Create rule templates + +As an AI generating configuration rules, +I want template files for each rule type with placeholder syntax, +So that I produce consistent, predictable output across repos. + +**Acceptance Criteria:** + +**Given** the directory `.agents/skills/agentic-os-setup/templates/` exists +**When** listing its contents +**Then** it contains: `persona-routing.md`, `scope-isolation.md`, `cross-reference.md`, `naming-enforcement.md`, `quality-gates.md` + +**Given** any template file +**When** an AI reads it +**Then** it contains: Intent, Inputs Required (with `{placeholder}` syntax), Output Pattern per runtime (Cursor .mdc, CLAUDE.md section, AGENTS.md section), and When to Use criteria +**And** the "When to Use" section specifies which complexity tiers and signals trigger this template + +### Story 2.4: Create calibration examples + +As an AI generating configuration, +I want reference examples showing expected output for different complexity tiers, +So that I calibrate my output volume and depth appropriately. + +**Acceptance Criteria:** + +**Given** the directory `.agents/skills/agentic-os-setup/examples/` exists +**When** listing its contents +**Then** it contains: `simple-output.md` and `complex-output.md` + +**Given** `simple-output.md` +**When** an AI reads it +**Then** it shows a complete example of tier 1-2 output (one config file per runtime, minimal) + +**Given** `complex-output.md` +**When** an AI reads it +**Then** it shows a complete example of tier 3-4 output (AGENTS.md, GOALS.md, runtime configs with persona routing, scope isolation, relationship enforcement) + +--- + +## Epic 3: Preview, Safety & Approval + +Users see exactly what will change, are protected from conflicts, and must explicitly approve before anything is written. + +### Story 3.1: Define diff preview protocol in SKILL.md + +As a user reviewing proposed changes, +I want all changes presented as unified diffs before anything is written, +So that I see exact content and maintain control. + +**Acceptance Criteria:** + +**Given** the SKILL.md approval workflow section +**When** an AI reaches the proposal stage +**Then** it presents all new files as full-content diffs (`--- /dev/null`, `+++ b/path`) +**And** extensions to existing files show the added sections only +**And** the format is compatible with standard diff tools +**And** the user can reject individual files while approving others + +### Story 3.2: Define dry-run mode in SKILL.md + +As a user who wants to preview without committing, +I want a dry-run mode that performs full analysis but writes nothing, +So that I can evaluate what would happen before deciding. + +**Acceptance Criteria:** + +**Given** SKILL.md mode detection section +**When** the AI detects dry-run intent (user says "dry run" or `--dry-run` was passed) +**Then** full scanning, classification, and proposal generation runs normally +**And** diffs are presented exactly as in normal mode +**And** zero files are written to disk +**And** no manifest is created + +### Story 3.3: Define conflict detection protocol in SKILL.md + +As a user with existing .cursor/rules/ files, +I want the AI to detect glob collisions before writing, +So that my existing setup is never silently broken. + +**Acceptance Criteria:** + +**Given** SKILL.md conflict detection section +**When** the AI is about to generate a .cursor/rules/ file +**Then** it first scans ALL existing .mdc files for their glob patterns +**And** if any proposed glob overlaps with an existing glob, it reports the collision +**And** the collision report includes: existing file name, its glob, proposed glob, and why they conflict +**And** on collision: AI proposes alternatives (narrower glob) or skips that rule + +**Given** an existing rule numbering convention (e.g., 800-805) +**When** the AI generates a new rule +**Then** it uses the next available number in the appropriate band (e.g., 806) +**And** it NEVER renumbers or moves existing files + +### Story 3.4: Define framework coexistence in SKILL.md + +As a user with BMAD or another agent framework installed, +I want agentic-os to detect it and defer persona ownership, +So that two persona systems don't conflict. + +**Acceptance Criteria:** + +**Given** SKILL.md framework coexistence section +**When** `_bmad/` directory is detected during scanning +**Then** AI does NOT generate persona routing rules +**And** generated rules are limited to: scope isolation, cross-reference enforcement, naming patterns +**And** the AI explains what it's deferring and why in the proposal + +--- + +## Epic 4: Runtime Adapters + +Users get semantically equivalent configuration in the native format of their chosen AI tools. + +### Story 4.1: Create Claude Code adapter + +As a Claude Code user, +I want generated CLAUDE.md that teaches Claude about my repo structure, +So that Claude Code gives contextually-aware responses. + +**Acceptance Criteria:** + +**Given** the file `.agents/skills/agentic-os-setup/adapters/claude.md` exists +**When** an AI reads it +**Then** it describes: file path (CLAUDE.md at repo root), format specification (markdown with sections/headers), constraints (what Claude Code can express), merge behavior (create new file), and 2+ concrete examples + +**Given** the adapter is used for a Multi-tier repo +**When** generating CLAUDE.md +**Then** output includes persona routing, execution rules, and quality gates sections +**And** references AGENTS.md for persona definitions where applicable + +### Story 4.2: Create Cursor adapter + +As a Cursor user, +I want generated .cursor/rules/NNN-agentic-os.mdc with proper frontmatter, +So that Cursor enforces agentic-os rules natively. + +**Acceptance Criteria:** + +**Given** the file `.agents/skills/agentic-os-setup/adapters/cursor.md` exists +**When** an AI reads it +**Then** it describes: file path convention (.cursor/rules/NNN-agentic-os.mdc), YAML frontmatter format (description, globs, alwaysApply), numbering rules (respect existing convention, default to 900 band if no convention), glob specificity rules (never `*` alone), and 2+ examples + +**Given** the adapter specifies glob collision detection +**When** the AI references this adapter +**Then** it knows to scan existing .mdc files before writing + +### Story 4.3: Create Cline adapter + +As a Cline user, +I want generated .clinerules configuration, +So that Cline follows agentic-os behavioral rules. + +**Acceptance Criteria:** + +**Given** the file `.agents/skills/agentic-os-setup/adapters/cline.md` exists +**When** an AI reads it +**Then** it describes: file path (.clinerules at repo root), format specification, constraints, merge behavior (create new file), and 2+ examples +**And** behavioral intent is semantically equivalent to Claude and Cursor outputs + +### Story 4.4: Create Antigravity adapter + +As an Antigravity user with an existing AGENTS.md, +I want agentic-os to extend my AGENTS.md with a managed block, +So that my original content is preserved while agentic-os rules are appended. + +**Acceptance Criteria:** + +**Given** the file `.agents/skills/agentic-os-setup/adapters/antigravity.md` exists +**When** an AI reads it +**Then** it describes: file path (AGENTS.md at repo root), format specification, merge behavior (EXTEND existing — never replace), managed block markers (canonical format: `` / ``), and 2+ examples showing extension pattern + +**Given** an existing AGENTS.md with user-written content +**When** the AI applies this adapter +**Then** user content stays intact above the managed block +**And** agentic-os rules are appended within the managed block below +**And** if no AGENTS.md exists, one is created entirely within managed markers + +--- + +## Epic 5: Manifest & State Management + +Users can track what was generated, cleanly uninstall, and have generated files gitignored by default. + +### Story 5.1: Define manifest schema in SKILL.md + +As a user who may want to uninstall later, +I want every generated file tracked in a manifest, +So that setup.sh --remove can cleanly undo everything. + +**Acceptance Criteria:** + +**Given** SKILL.md write protocol section +**When** the AI writes any file +**Then** it also writes/updates `.agents/.agentic-os-manifest.json` with: version, created_at, complexity_tier, runtimes_targeted, files array (path, created_at, content_hash), denied_relationships, detected_frameworks + +**Given** the manifest schema +**When** setup.sh --remove reads it +**Then** it can parse the JSON with standard tools (jq or shell parsing) +**And** the files array provides exact paths for deletion + +### Story 5.2: Define gitignore management in SKILL.md + +As a user who doesn't want generated configs committed, +I want generated files gitignored by default, +So that my team structure and tooling aren't exposed in public repos. + +**Acceptance Criteria:** + +**Given** SKILL.md write protocol section +**When** the AI writes files and `--track` was NOT passed +**Then** it appends a clearly delimited block to .gitignore: +``` +# === AGENTIC-OS GENERATED (do not edit this block) === + +# === END AGENTIC-OS GENERATED === +``` +**And** the block is at the end of .gitignore (append-only) + +**Given** `--track` was passed during setup +**When** the AI writes files +**Then** .gitignore is NOT modified +**And** generated files are intended to be committed + +--- + +## Epic 6: Documentation & Contributing + +Users and contributors can understand the feature and how to extend it. + +### Story 6.1: Update README.md + +As a user discovering agentic-os, +I want the README to document both classic and AI-assisted setup paths, +So that I know my options immediately. + +**Acceptance Criteria:** + +**Given** the README.md Quick Start section +**When** a user reads it +**Then** it shows classic `./setup.sh` as step 2 +**And** immediately below, shows AI-assisted as alternative: `./setup.sh --ai --runtime claude,cursor` +**And** briefly explains when to use each (simple project → classic, existing project → AI-assisted) + +**Given** the Architecture mermaid diagram +**When** updated +**Then** it includes the AI-installer skill as a component +**And** shows its relationship to other system components + +**Given** the README +**When** a user reads the AI-assisted setup section +**Then** it includes a new mermaid flow diagram showing the AI-assisted setup flow: `setup.sh --ai` → skill dropped → user invokes AI → scan → classify → propose → approve → generate +**And** the diagram clearly shows the three modes (first-run, dry-run, re-run placeholder) + +**Given** the Agent Compatibility section +**When** updated +**Then** it lists Cursor, Cline, and Antigravity alongside existing runtimes +**And** mentions the `--runtime` flag for targeting + +**Given** the File System Layout +**When** updated +**Then** it shows `.agents/skills/agentic-os-setup/` with brief description + +### Story 6.2: Create CONTRIBUTING.md ✅ FULFILLED + +**Status:** Already implemented as part of this planning work. CONTRIBUTING.md exists at repo root with full content covering signals, templates, adapters, testing protocol, and PR standards. + +As a potential contributor, +I want clear guidance on how to extend the AI-installer (signals, templates, adapters), +So that I can contribute without reverse-engineering the system. + +**Acceptance Criteria:** + +**Given** CONTRIBUTING.md exists at repo root +**When** a contributor reads it +**Then** it covers: how to add signals, templates, and adapters with exact format examples +**And** includes development workflow (fork, branch, test, PR) +**And** references the license (CC BY-NC-SA 4.0) +**And** documents manual testing protocol (test repos, verification steps, coexistence checks) +**And** defines what makes a good PR (atomic, tested, documented, non-breaking) + +--- + +## Epic 7: Test Infrastructure + +Developers and contributors can validate setup.sh behavior and generated content quality through automated tests running against real repo fixtures. + +### Story 7.1: Create test repo fixtures + +As a developer testing the AI-installer, +I want real directory structures that mimic each user journey, +So that I can run `setup.sh --ai --target` against them and validate end-to-end behavior. + +**Acceptance Criteria:** + +**Given** the `examples/` directory exists +**When** listing its contents +**Then** it contains 4 subdirectories: `uj-1-node-monorepo/`, `uj-2-architect-monorepo/`, `uj-3-flask-simple/`, `uj-4-rust-antigravity/` + +**Given** `examples/uj-1-node-monorepo/` +**When** examining its structure +**Then** it contains: `package.json` (with workspaces field), `.cursor/rules/` with 3 `.mdc` files (002-dates.mdc, 003-eslint.mdc, 005-api.mdc), `packages/api/package.json`, `packages/web/package.json`, `src/`, `tests/` +**And** each .mdc file has valid YAML frontmatter with description and globs + +**Given** `examples/uj-2-architect-monorepo/` +**When** examining its structure +**Then** it contains: `Designs/`, `Operations/job-descriptions/`, `Operations/job-interviews/`, `Team-Workitems/`, `Infrastructure/`, `_bmad/`, `.cursor/rules/` with 10 files in 800-band, `AGENTS.md` with existing user content + +**Given** `examples/uj-3-flask-simple/` +**When** examining its structure +**Then** it contains: `src/app.py`, `tests/`, `requirements.txt`, `README.md` +**And** no existing AI configuration files + +**Given** `examples/uj-4-rust-antigravity/` +**When** examining its structure +**Then** it contains: `Cargo.toml` (with [workspace] members = ["api", "core", "shared"]), `api/Cargo.toml`, `core/Cargo.toml`, `shared/Cargo.toml`, `AGENTS.md` with existing user-written content + +### Story 7.2: Create shell test runner + +As a developer modifying setup.sh, +I want an automated test script that validates flag parsing and mode routing, +So that regressions are caught immediately. + +**Acceptance Criteria:** + +**Given** the file `tests/test_setup.sh` exists and is executable +**When** a developer runs it +**Then** it tests: --help output correctness, --ai routes to AI mode, --runtime validates valid/invalid values, --remove without manifest exits cleanly, --remove with manifest deletes tracked files, --target with valid path works, --target with invalid path errors, --auto without --runtime errors, --auto with --runtime sets context bridge correctly, flag combinations (--ai --dry-run --runtime, --ai --auto --runtime --target) +**And** results are written to `tests/results/shell/` +**And** exit code is 0 if all pass, non-zero on any failure + +**Given** the test runner uses POSIX sh +**When** it runs +**Then** it requires no dependencies beyond sh, jq, and standard tools (grep, diff, rm, mkdir) + +### Story 7.3: Create Python content validator + +As a developer modifying templates or adapters, +I want automated validation that generated content meets structural requirements, +So that format regressions are caught before merge. + +**Acceptance Criteria:** + +**Given** the file `tests/test_content.py` exists +**When** a developer runs `pytest tests/test_content.py` +**Then** it validates against pre-generated content in `tests/results/python/`: +- Manifest JSON is valid and matches schema (version, files array, content_hash format) +- .mdc files have valid YAML frontmatter (description, globs fields present) +- No .mdc file uses bare `*` as its glob +- Managed block markers match canonical format (``) +- Gitignore block has start/end delimiters +- Cursor file numbering doesn't conflict with existing fixtures +**And** results are written to `tests/results/python/report.xml` (JUnit XML) and `tests/results/python/report.txt` (plaintext) +**And** `pytest.ini` configures test paths and XML output; `tests/conftest.py` generates plaintext report + +**Given** the test suite covers 5 scenarios +**When** examining test cases +**Then** scenarios are: (1) simple project output validation, (2) complex project with BMAD deferral, (3) collision detection on overlapping globs, (4) clean uninstall leaves zero artifacts, (5) auto-mode completes without interaction + +### Story 7.4: Configure test results gitignore + +As a developer running tests locally, +I want test output to be gitignored, +So that generated artifacts don't pollute the repository. + +**Acceptance Criteria:** + +**Given** the repo's `.gitignore` +**When** examining its contents +**Then** it includes `tests/results/` + +**Given** a developer runs the test suite +**When** tests complete +**Then** all output (generated files, logs, reports) is written under `tests/results/` +**And** no tracked files are modified by the test run diff --git a/_bmad-output/prd-ai-assisted-setup-2026-06-20/implementation-readiness-report.md b/_bmad-output/prd-ai-assisted-setup-2026-06-20/implementation-readiness-report.md new file mode 100644 index 0000000..88031aa --- /dev/null +++ b/_bmad-output/prd-ai-assisted-setup-2026-06-20/implementation-readiness-report.md @@ -0,0 +1,251 @@ +# Implementation Readiness Assessment Report + +**Date:** 2026-06-20 +**Project:** AI-Assisted Complex Repo Auto-Setup +**Assessor:** BMad Implementation Readiness Check + +--- + +## Document Discovery + +### Documents Found + +| Type | File | Status | +|------|------|--------| +| PRD | prd.md | ✅ Found (31 FRs, 7 NFRs) | +| Architecture | architecture.md | ✅ Found (11 decisions) | +| Epics & Stories | epics.md | ✅ Found (7 epics, 27 stories) | +| Addendum | addendum.md | ✅ Found (supporting detail) | +| Decision Log | .decision-log.md | ✅ Found (6 decisions) | +| UX Design | N/A | ⬜ Not applicable (file-based system, no UI) | + +**No duplicates. No missing required documents.** + +--- + +## PRD Analysis + +### Functional Requirements Extracted + +Total FRs: **31** (FR-1 through FR-31) + +- FR-1 to FR-4: Bootstrap entry point (flags, runtime targeting, uninstall, discoverability) +- FR-5 to FR-9: AI-installer skill core (scanning, classification, proposal, relationships, catalog) +- FR-10 to FR-12: Preview & approval (diffs, dry-run, approval gate) +- FR-13 to FR-16: Safety (glob collision, numbering, non-destructive, framework coexistence) +- FR-17 to FR-20: Runtime adapters (Claude, Cursor, Cline, Antigravity) +- FR-21 to FR-22: Manifest & state (tracking, gitignore) +- FR-23 to FR-24: Documentation (README, CONTRIBUTING.md) +- FR-25 to FR-26: Target directory, auto-approval mode +- FR-27 to FR-30: Test infrastructure (fixtures, shell runner, Python validator, gitignore) + +### Non-Functional Requirements Extracted + +Total NFRs: **7** (NFR-1 through NFR-7) + +- NFR-1: Zero regression to existing setup.sh +- NFR-2: Cross-platform (macOS, Linux, WSL) +- NFR-3: POSIX sh compatible +- NFR-4: Minimal external dependencies (git, jq); setup.sh verifies jq before --remove +- NFR-5: Privacy-respecting scan +- NFR-6: Generated files gitignored by default + +### Additional Requirements (from Architecture) + +- AR-1: Managed block markers from Phase 1 +- AR-2: Contributor-friendly signal catalog format +- AR-3: Placeholder syntax in templates +- AR-4: Adapters as reference docs +- AR-5: JSON manifest for shell parseability +- AR-6: Single SKILL.md entry point + +### PRD Completeness Assessment + +**Strong.** The PRD has clear FR numbering, testable consequences, 4 user journeys covering all runtimes, explicit non-goals, phased scope, and success metrics with counter-metrics. Open questions (5) are non-blocking for Phase 1. + +--- + +## Epic Coverage Validation + +### FR Coverage Matrix + +| FR | PRD Requirement | Epic Coverage | Status | +|----|----------------|---------------|--------| +| FR-1 | Flag-based mode selection | Epic 1, Story 1.1 | ✅ Covered | +| FR-2 | Runtime targeting | Epic 1, Story 1.2 | ✅ Covered | +| FR-3 | Clean uninstall | Epic 1, Story 1.3 | ✅ Covered | +| FR-4 | Discoverability | Epic 1, Story 1.4 | ✅ Covered | +| FR-5 | Repo structure scanning | Epic 2, Story 2.1 | ✅ Covered | +| FR-6 | Complexity classification | Epic 2, Story 2.1 | ✅ Covered | +| FR-7 | Configuration proposal | Epic 2, Story 2.1 | ✅ Covered | +| FR-8 | Relationship discovery | Epic 2, Story 2.1 | ✅ Covered | +| FR-9 | Signal catalog | Epic 2, Story 2.2 | ✅ Covered | +| FR-10 | Unified diff preview | Epic 3, Story 3.1 | ✅ Covered | +| FR-11 | Dry-run mode | Epic 3, Story 3.2 | ✅ Covered | +| FR-12 | Approval gate | Epic 3, Story 3.1 | ✅ Covered | +| FR-13 | Glob collision detection | Epic 3, Story 3.3 | ✅ Covered | +| FR-14 | Existing rule numbering | Epic 3, Story 3.3 | ✅ Covered | +| FR-15 | Non-destructive file policy | Epic 3, Story 3.3 | ✅ Covered | +| FR-16 | Framework coexistence | Epic 3, Story 3.4 | ✅ Covered | +| FR-17 | Claude Code adapter | Epic 4, Story 4.1 | ✅ Covered | +| FR-18 | Cursor adapter | Epic 4, Story 4.2 | ✅ Covered | +| FR-19 | Cline adapter | Epic 4, Story 4.3 | ✅ Covered | +| FR-20 | Antigravity adapter | Epic 4, Story 4.4 | ✅ Covered | +| FR-21 | Manifest tracking | Epic 5, Story 5.1 | ✅ Covered | +| FR-22 | Gitignore management | Epic 5, Story 5.2 | ✅ Covered | +| FR-23 | README update | Epic 6, Story 6.1 | ✅ Covered | +| FR-24 | CONTRIBUTING.md | Epic 6, Story 6.2 | ✅ Covered | +| FR-25 | Target directory | Epic 1, Story 1.5 | ✅ Covered | +| FR-26 | Auto-approval mode | Epic 1, Story 1.6 | ✅ Covered | +| FR-27 | Test repo fixtures | Epic 7, Story 7.1 | ✅ Covered | +| FR-28 | Shell test runner | Epic 7, Story 7.2 | ✅ Covered | +| FR-29 | Python content validator | Epic 7, Story 7.3 | ✅ Covered | +| FR-30 | Test results gitignored | Epic 7, Story 7.4 | ✅ Covered | +| FR-31 | Workspace bootstrapping | Epic 2, Story 2.5 | ✅ Covered | + +### Coverage Statistics + +- Total PRD FRs: 31 +- FRs covered in epics: 31 +- **Coverage: 100%** + +### Missing Requirements + +**None.** All 31 FRs are mapped to specific stories. + +### NFR Coverage Check + +| NFR | Addressed In | +|-----|-------------| +| NFR-1 (zero regression) | Story 1.1 AC explicitly tests unchanged behavior | +| NFR-2 (cross-platform) | Architecture Decision 2 (POSIX sh) | +| NFR-3 (POSIX compatible) | Architecture Decision 2 | +| NFR-4 (minimal deps: git, jq) | Architecture constraint; setup.sh checks jq | +| NFR-5 (privacy scan) | Story 2.1 AC (scanning protocol: don't read file contents) | +| NFR-6 (gitignored default) | Story 5.2 | +| NFR-7 (test results isolated) | Story 7.4 | + +--- + +## UX Alignment + +**Not applicable.** This is a file-based system with no UI. The "UX" is the conversation between the user and their AI tool, which is governed by SKILL.md content — covered in Epic 2. + +--- + +## Epic Quality Review + +### Epic Structure Validation + +#### User Value Focus Check + +| Epic | User-Value Title? | User Outcome? | Standalone? | +|------|:-----------------:|:-------------:|:-----------:| +| 1. Bootstrap Entry Point | ✅ | "Users can invoke, target, uninstall" | ✅ | +| 2. AI-Installer Skill Core | ✅ | "Users can have repo analyzed" | ✅ | +| 3. Preview, Safety & Approval | ✅ | "Users see what changes, are protected" | ✅ | +| 4. Runtime Adapters | ✅ | "Users get native config per tool" | ✅ | +| 5. Manifest & State | ⚠️ Borderline | "Users can track/uninstall" | ✅ | +| 6. Documentation | ✅ | "Users/contributors understand the system" | ✅ | + +**Epic 5 note:** "Manifest & State Management" is borderline technical — but the user value IS clear: "I can cleanly uninstall" and "my generated files stay private." Acceptable as-is since it directly enables UJ-1 (clean removal confidence). + +#### Epic Independence Validation + +- **Epic 1:** Fully standalone (just the shell script) +- **Epic 2:** Independent — creates SKILL.md and supporting files (doesn't depend on generated output) +- **Epic 3:** Depends on Epic 2 (SKILL.md must exist to define preview/safety protocols) — **acceptable sequential dependency** +- **Epic 4:** Depends on Epic 2 (adapters are referenced by SKILL.md) — **acceptable** +- **Epic 5:** Depends on Epic 2 (manifest written by SKILL.md) — **acceptable** +- **Epic 6:** Independent (README/CONTRIBUTING can be written anytime) + +**No circular dependencies. No forward dependencies. All epics can function with only prior epics completed.** + +### Story Quality Assessment + +#### Story Sizing + +All 27 stories produce 1-2 files each. Every story is a concrete file-creation task appropriate for a single dev agent session. No "create everything" mega-stories. + +#### Acceptance Criteria Review + +| Quality Check | Pass/Fail | Notes | +|--------------|:---------:|-------| +| Given/When/Then format | ✅ | All stories use BDD structure | +| Testable criteria | ✅ | Each AC is independently verifiable | +| Error conditions covered | ⚠️ | Some stories could add error ACs (see findings) | +| Specific outcomes | ✅ | Clear expected results throughout | + +#### Dependency Analysis (Within-Epic) + +**Epic 1:** Stories 1.1→1.2→1.3→1.4 are independent (each modifies setup.sh separately) +**Epic 2:** Story 2.1 (SKILL.md) should come first; 2.2-2.4 are independent leaf files +**Epic 3:** Stories 3.1-3.4 define sections of SKILL.md — all depend on Story 2.1 existing +**Epic 4:** Stories 4.1-4.4 are fully independent (one file each, no dependencies) +**Epic 5:** Stories 5.1-5.2 define SKILL.md sections — depend on Story 2.1 +**Epic 6:** Stories 6.1-6.2 are independent + +**No forward dependencies within any epic.** + +### Findings by Severity + +#### 🟡 Minor Concerns (3) + +**1. Story 1.3 (--remove) references manifest but manifest is defined in Epic 5** + +The shell script's --remove logic needs to know the manifest schema. Currently, the manifest format is defined in Story 5.1. This creates a cross-epic implementation dependency. + +**Recommendation:** Add a note to Story 1.3 that the manifest JSON schema must be defined before --remove can be fully implemented. Or move manifest schema definition to an earlier story. **Low risk** — the schema is simple and fixed in architecture. + +**2. Epic 3 stories define SKILL.md sections but SKILL.md is created in Epic 2 Story 2.1** + +Stories 3.1-3.4 add sections to SKILL.md. If implemented sequentially (Epic 2 first, then Epic 3), this is fine. But the dependency should be explicit. + +**Recommendation:** Accept as-is — epic sequencing handles this naturally. Implementation order must be: Epic 2 → Epic 3. + +**3. Some stories lack negative/error ACs** + +Stories 2.2 (signal catalog) and 2.4 (examples) don't specify what happens if the files are malformed or missing. + +**Recommendation:** Accept as-is for Phase 1 — these are static reference files written by contributors, not generated at runtime. Malformation is a contributor error caught in PR review, not a runtime concern. + +#### No 🔴 Critical Violations found. +#### No 🟠 Major Issues found. + +--- + +## Summary and Recommendations + +### Overall Readiness Status + +## ✅ READY + +This project is ready for implementation. All requirements are traced, all epics deliver user value, stories are properly sized, and the architecture is coherent. + +### Critical Issues Requiring Immediate Action + +**None.** No blocking issues found. + +### Minor Issues (Non-blocking) + +1. Cross-epic manifest schema dependency (Story 1.3 ↔ Story 5.1) — mitigated by implementation sequencing +2. SKILL.md section ordering (Epic 3 depends on Epic 2) — mitigated by natural epic flow +3. Some stories could have richer error-case ACs — acceptable for Phase 1 (static files) + +### Recommended Implementation Order + +1. **Epic 6 (Documentation)** — Can be done immediately, sets contributor context +2. **Epic 1 (Bootstrap)** — Shell script changes, independent (includes --target, --auto) +3. **Epic 2 (AI-Installer Core)** — SKILL.md + supporting files +4. **Epic 4 (Runtime Adapters)** — Independent leaf files, parallelizable +5. **Epic 3 (Preview & Safety)** — Adds sections to SKILL.md (depends on Epic 2) +6. **Epic 5 (Manifest & State)** — Adds write protocol to SKILL.md (depends on Epic 2) +7. **Epic 7 (Test Infrastructure)** — Fixtures + test runners (depends on Epics 1-5 being complete) + +**Note:** Epics 4, 3, and 5 can be parallelized since they all add independent sections to SKILL.md. Epic 7 runs last because tests validate the implemented system. + +### Final Note + +This assessment identified **3 minor issues** across **1 category** (cross-epic sequencing). All are mitigated by natural implementation order and none require artifact changes. The project has 100% FR coverage, clean epic structure, proper story sizing, and complete acceptance criteria. + +**Proceed to implementation.** diff --git a/_bmad-output/prd-ai-assisted-setup-2026-06-20/prd.md b/_bmad-output/prd-ai-assisted-setup-2026-06-20/prd.md new file mode 100644 index 0000000..413a416 --- /dev/null +++ b/_bmad-output/prd-ai-assisted-setup-2026-06-20/prd.md @@ -0,0 +1,541 @@ +--- +title: AI-Assisted Complex Repo Auto-Setup +status: draft +created: 2026-06-20 +updated: 2026-06-20 +--- + +# PRD: AI-Assisted Complex Repo Auto-Setup + +## 0. Document Purpose + +This PRD defines the requirements for extending agentic-os with an AI-assisted setup path that detects existing repository structure, classifies complexity, and generates appropriately-scoped configuration — without breaking the existing `setup.sh` questionnaire flow. It targets the upstream maintainer and contributors of itseffi/agentic-os as primary audience, and downstream users who will invoke the feature. The PRD uses stable FR IDs for traceability into architecture and implementation. + +## 1. Vision + +Agentic-os today assumes a greenfield personal workspace: five questions, a GOALS.md, some directories. But most developers who discover it already have a project — often a complex one with multiple concerns, existing AI configurations, team structures, and cross-domain relationships. They cannot use agentic-os without manually figuring out how to map their repo into the OS's expectations. + +This feature makes agentic-os smart enough to meet users where they are. By shipping an AI-installer skill alongside the existing setup script, users invoke their AI tool of choice (Claude Code, Cursor, Cline, or Antigravity) and the AI analyzes the repo, proposes configuration proportional to detected complexity, previews everything as a diff, and only writes after human approval. The result: agentic-os works for a solo dev's weekend project AND an architect's multi-team monorepo — same tool, different output depth. + +The paradigm shift: setup is no longer a script that asks questions and writes files. Setup IS the AI reading the repo and configuring itself. The script becomes a bootstrap; the AI becomes the installer. + +## 2. Target User + +### 2.1 Jobs To Be Done + +- I want my AI tools to immediately understand my existing project structure without me manually writing config files (functional) +- I want to adopt agentic-os on an existing repo without breaking my current AI setup (functional, emotional — fear of disruption) +- I want configuration proportional to my repo's actual complexity, not a one-size-fits-all template (functional) +- I want to see what will change before anything is written, so I maintain control (emotional — trust, autonomy) +- I want to cleanly remove agentic-os if it doesn't work for me (emotional — commitment anxiety) + +### 2.2 Non-Users (v1) + +- Teams wanting fully automated CI/CD pipeline integration (multi-stage, artifact caching, cross-repo orchestration) — v1's `--auto` supports single-repo unattended runs but not full CI/CD workflows +- Users who only use the classic questionnaire and never want AI involvement — classic path remains untouched +- Users of runtimes not in v1 scope (GitHub Copilot, Kiro, Codex, Pi) — future phases + +### 2.3 Key User Journeys + +**UJ-1. Alex sets up agentic-os on their existing Node.js monorepo from Cursor.** + +- **Persona + context:** Alex, mid-level full-stack dev, has 3 .cursor/rules files they wrote over 6 months. Uses Cursor daily, just started trying Claude Code. +- **Entry state:** Terminal, in project root. Has cloned agentic-os or copied files in. +- **Path:** Runs `setup.sh --ai --runtime cursor,claude`. Script verifies `.agents/skills/agentic-os-setup/` exists, writes setup context, prints: "AI-installer skill ready. Open Cursor and say: run the agentic-os setup skill." Alex opens Cursor, invokes the skill. AI scans repo, reports: "Detected: Node.js monorepo, 3 existing cursor rules (002-dates.mdc, 003-eslint.mdc, 005-api.mdc), complexity tier: Multi. I'd generate: .cursor/rules/900-agentic-os.mdc, CLAUDE.md, and AGENTS.md. No conflicts with existing rules." Alex reviews the unified diff preview, says "looks good." AI writes files. +- **Climax:** Alex immediately asks Cursor a question about their API routes and gets a response that references agentic-os context — tangibly better than before. +- **Resolution:** Three new files exist. Original rules untouched. Alex knows they can `setup.sh --remove` if needed. +- **Edge case:** If AI detects glob overlap with existing rule 005-api.mdc, it aborts with conflict report and asks Alex to resolve. + +**UJ-2. Sam, a senior architect, adds agentic-os to their multi-team documentation monorepo.** + +- **Persona + context:** Sam manages a repo with designs, team work items, job postings, infrastructure-as-code, and 3 teams. Has BMAD installed, 10+ cursor rules, MCP integrations. +- **Entry state:** Terminal, project root. Wants agentic-os to handle cross-domain rules and task routing. +- **Path:** Runs `setup.sh --ai --runtime claude,cursor,cline`. AI scans, reports: "Detected: complex tier. 5 concern domains (Designs, Operations, Team-Workitems, Infrastructure, Meetings). Existing AI config: _bmad/ (deferring persona ownership), .cursor/rules/ (10 files, 0XX-9XX numbering). I'd generate: AGENTS.md, GOALS.md, .cursor/rules/850-agentic-os.mdc (next available in 8XX band), CLAUDE.md, .clinerules. Proposed relationships: job-interviews → job-descriptions (confirm?), Team-Workitems → Designs (confirm?)." Sam confirms relationships, reviews diff, approves. +- **Climax:** Cross-domain linkage enforcement is active — AI now refuses to create interview notes without linking to job description. Scope isolation prevents context bleed between teams. +- **Resolution:** Agentic-os config lives alongside BMAD without conflict. Generated files are gitignored. Sam can re-run later when adding new folders. + +**UJ-3. Jordan, a student, tries agentic-os on their Flask project for the first time.** + +- **Persona + context:** Jordan just installed Claude Code extension yesterday. No existing AI config. Small Flask API project. +- **Entry state:** Terminal, project root. Ran `setup.sh` (no flags) and completed the classic questionnaire. +- **Path:** Classic setup finishes. Final output says: "Want smarter, AI-powered setup? Run: setup.sh --ai". Jordan is curious, runs it with `--runtime claude`. AI scans: "Detected: simple tier. Flask app with src/, tests/, requirements.txt. I'd generate: CLAUDE.md that teaches Claude about your Flask routes, models, and test patterns." Jordan sees a short diff, approves. +- **Climax:** Jordan asks Claude about their project and gets an answer that references their actual route structure — first "wow, it knows my code" moment. +- **Resolution:** One file generated (CLAUDE.md). Minimal, immediately valuable. Jordan keeps using it. + +**UJ-4. Riley sets up agentic-os using Antigravity on their Rust microservices project.** + +- **Persona + context:** Riley, a backend engineer, uses Antigravity as their primary AI coding tool. Has an existing AGENTS.md from a previous manual setup attempt. Runs a Rust workspace with 3 crates (api, core, shared). +- **Entry state:** Terminal, workspace root. Antigravity already configured and running. +- **Path:** Runs `setup.sh --ai --runtime antigravity`. Script verifies skill exists, writes setup context, prints: "AI-installer skill ready. Open Antigravity and say: run the agentic-os setup skill." Riley invokes the skill. AI scans: "Detected: Multi tier. Rust workspace with 3 crates. Existing AGENTS.md found — I'll extend it with agentic-os sections rather than replace. I'd add: persona routing (api crate → API designer, core → systems engineer), scope isolation between crates, and quality gate (cargo test must pass before declaring done)." Riley reviews the diff showing additions to AGENTS.md, approves. +- **Climax:** Riley asks Antigravity about a cross-crate dependency and gets a response scoped to the correct crate context — the AI respects the scope isolation rules. +- **Resolution:** AGENTS.md extended (not replaced). Manifest tracks the managed sections. Riley's original AGENTS.md content is preserved above the managed block. +- **Edge case:** If the existing AGENTS.md has conflicting persona definitions, AI proposes reconciliation options rather than silently appending. + +## 3. Glossary + +- **AI-installer skill** — A SKILL.md file containing a reasoning framework, signal catalog, and rule templates that any supported AI runtime can execute to configure agentic-os for the current repo. +- **Signal catalog** — A structured list of filesystem markers (file names, folder patterns, config files) and what they indicate about a repo's purpose, complexity, and existing tooling. +- **Complexity tier** — Classification of a repo's configuration needs: Zero (empty), Simple (single-purpose), Multi (2-3 concerns), Complex (4+ concerns, teams, cross-domain relationships). +- **Runtime adapter** — The component of the AI-installer skill that translates a configuration intent into the native format of a specific AI tool (CLAUDE.md for Claude Code, .mdc for Cursor, .clinerules for Cline, AGENTS.md for Antigravity). +- **Managed block** — A section of a generated file delimited by markers (e.g., ``) that the re-run system owns. Checksum guards prevent overwriting user edits. +- **Dry-run** — A mode where the AI-installer previews all proposed changes as unified diffs without writing any files. +- **Re-run** — A mode where the AI-installer detects changes since the last run and proposes only the delta. +- **Relationship** — A semantic link between two folders/concerns (e.g., interviews reference job descriptions). Can be manifest-declared (trusted) or AI-proposed (requires confirmation). +- **Glob collision** — When a generated .mdc rule's glob pattern overlaps with an existing rule's glob, causing unpredictable behavior in Cursor. +- **Scope isolation** — A rule type that prevents AI context from one domain (e.g., Operations) bleeding into another (e.g., Designs). + +## 4. Features + +### 4.1 Bootstrap Entry Point + +**Description:** The existing `setup.sh` gains an `--ai` flag that bootstraps the AI-assisted setup path. Without `--ai`, behavior is 100% unchanged. The flag drops the AI-installer skill into the canonical skills location and prints clear instructions for the user's next step. The classic setup's completion message also surfaces the `--ai` option for discoverability. Realizes UJ-1, UJ-2, UJ-3, UJ-4. + +**Functional Requirements:** + +#### FR-1: Flag-based mode selection + +The user can run `setup.sh --ai` to enable AI-assisted setup. Running `setup.sh` without flags executes the existing classic questionnaire with zero behavioral change. + +**Consequences (testable):** +- `setup.sh` without flags produces identical output to current behavior (regression test) +- `setup.sh --ai` bootstraps workspace infrastructure into target, writes setup context file, and prints invocation instructions (including `/agentic-os-setup` slash command for Claude Code) +- `setup.sh --ai` does NOT execute the classic questionnaire +- `setup.sh --help` prints usage information for all flags and exits +- The SKILL.md includes YAML frontmatter (`name:`, `description:`) enabling Claude Code slash-command discovery via the `.claude/skills/` bridge path + +#### FR-2: Runtime targeting + +The user can specify which AI runtimes to configure via `--runtime `. Valid values for v1: `claude`, `cursor`, `cline`, `antigravity`. Omitting `--runtime` defaults to all detected runtimes. + +**Consequences (testable):** +- `setup.sh --ai --runtime claude,cursor` generates configs only for Claude Code and Cursor +- Invalid runtime names produce a clear error message listing valid options +- When `--runtime` is omitted, the AI-installer skill detects which runtimes are present (by checking for `.claude/`, `.cursor/`, `.clinerules`, `AGENTS.md`) + +#### FR-3: Clean uninstall + +The user can run `setup.sh --remove` to cleanly remove all agentic-os generated files and restore the repo to its pre-setup state. + +**Consequences (testable):** +- `setup.sh --remove` deletes only files created by agentic-os (tracked in a manifest file `.agents/.agentic-os-manifest.json`) +- Original user files are never modified or deleted +- Removal also deletes the setup context file (`.agents/.agentic-os-setup-context.json`) and the manifest itself +- Removal produces a summary of what was deleted +- After removal, no agentic-os setup artifacts remain + +#### FR-4: Discoverability + +The classic `setup.sh` completion message includes a one-line prompt about the `--ai` option. + +**Consequences (testable):** +- After classic setup completes, output includes: "Want AI-powered setup? Run: setup.sh --ai" +- The prompt is a single line, not a wall of text + +#### FR-25: Target directory + +The user can specify a target directory via `--target ` to run setup against a repo other than CWD. + +**Consequences (testable):** +- `setup.sh --ai --target ./my-project` operates on `./my-project` instead of CWD +- All file reads and writes resolve relative to the target directory +- If `--target` is omitted, CWD is used (unchanged default) +- If the target path does not exist, the script exits with a clear error +- Works with both `--ai` and `--remove` modes +- setup.sh copies the agentic-os-setup skill and workspace infrastructure into the target directory during bootstrap, so all files are local when the AI runs +- No external path references in the context bridge — the AI finds everything at `.agents/skills/agentic-os-setup/` locally + +#### FR-26: Auto-approval mode + +The user can pass `--auto` alongside `--ai` to run the full AI-assisted setup without interactive approval. The AI shows the diff preview then immediately writes without waiting for user confirmation. + +**Consequences (testable):** +- `setup.sh --ai --auto --runtime claude` runs full flow: scan → classify → propose → show preview → write (no pause) +- `--auto` REQUIRES explicit `--runtime` (cannot auto-detect in unattended mode) — exits with error if `--runtime` is missing +- The context bridge file contains `"auto": true` when this flag is passed +- Auto mode still shows the diff preview output (for logging/CI purposes) +- Auto mode still respects `--dry-run` (if both passed: show diffs, write nothing) +- Auto mode does NOT skip conflict detection — if collisions are found, the run fails with a non-zero exit code rather than silently overwriting + +**Out of Scope:** +- GUI or web-based setup interface +- Automatic runtime detection in the shell script itself (that's the AI's job) + +### 4.2 AI-Installer Skill + +**Description:** The core of the feature — a SKILL.md file that any supported AI runtime can execute. Contains a reasoning framework for analyzing repos, a signal catalog for anchoring detection, rule templates for generating config, output examples for calibration, and runtime adapters for multi-tool output. Realizes UJ-1, UJ-2, UJ-3, UJ-4. + +**Functional Requirements:** + +#### FR-31: Workspace bootstrapping + +When invoked against a target repo, the AI-installer first bootstraps the full agentic-os workspace structure before generating configuration. This replaces the classic setup's questionnaire with repo-analysis-based inference. + +**Consequences (testable):** +- `Tasks/` and `Knowledge/` directories are created if not present +- `AGENTS.md` is copied from agentic-os source if not present in target +- `GOALS.md` is auto-generated with AI-inferred content (role, vision, priorities derived from repo signals) — inferred fields marked with `[AI-inferred — refine as needed]` +- `BACKLOG.md` is created with standard template if not present +- `Workflows/` directory is copied from agentic-os source if not present +- `.agents/skills/` directory (all canonical skill packs) is copied if not present +- `.claude/skills/` bridge ensured: if no `.claude/skills` exists, creates a symlink to `../.agents/skills`; if `.claude/skills` already exists as a directory, copies `agentic-os-setup` into it directly. `skills → .agents/skills` symlink created at root. +- `.gitignore` copied from template if not present (never overwrites existing) +- `CLAUDE.md` created with `@AGENTS.md` reference if not present (never overwrites existing) +- All bootstrapped files are tracked in the manifest for clean removal +- Existing files are NEVER overwritten during bootstrap — skip and note + +#### FR-5: Repo structure scanning + +When invoked, the AI-installer skill reads the repo's filesystem structure (directories, key files, existing config files) and builds a structural profile. + +**Consequences (testable):** +- Skill identifies top-level directories and their likely purpose +- Skill detects existing AI configurations (.cursor/rules/, .claude/, .clinerules, _bmad/, AGENTS.md) +- Skill reads manifest/README files if present for declared relationships +- Skill does NOT read file contents beyond config files and manifests (privacy-respecting scan) + +#### FR-6: Complexity classification + +The AI-installer classifies the repo into one of four complexity tiers based on detected signals: Zero (empty/new), Simple (single-purpose), Multi (2-3 concerns), Complex (4+ concerns). + +**Consequences (testable):** +- A repo with only src/ and tests/ is classified as Simple +- A repo with src/, docs/, and infrastructure/ is classified as Multi +- A repo with 4+ distinct concern folders, existing AI config, and team indicators is classified as Complex +- Classification is proposed to the user with rationale, not silently applied + +#### FR-7: Configuration proposal + +Based on complexity tier and detected structure, the AI-installer proposes a set of files to generate, with content tailored to the specific repo. + +**Consequences (testable):** +- Simple tier: proposes at most 1 config file per targeted runtime +- Multi tier: proposes runtime configs + lightweight AGENTS.md +- Complex tier: proposes full suite (AGENTS.md, GOALS.md, runtime configs with persona routing, scope isolation, relationship enforcement) +- Every proposal includes the full content that would be written (not just file names) + +#### FR-8: Relationship discovery + +The AI-installer detects cross-domain relationships via two paths: (1) manifest-declared relationships are trusted without confirmation, (2) AI-inferred relationships are proposed with rationale and require explicit user confirmation. + +**Consequences (testable):** +- If a manifest file declares "interviews → job-descriptions", this relationship is included without asking +- If the AI infers a relationship from folder naming patterns, it asks: "I think X relates to Y because Z — confirm?" +- User can deny an inferred relationship and it is excluded from generated config +- Denied relationships are not re-proposed on re-run + +#### FR-9: Signal catalog + +The skill includes a structured catalog of known filesystem signals and their meanings, used to anchor the AI's reasoning and prevent hallucination. The skill also includes `agents/openai.yaml` to comply with the repo's Agent Skills open standard (progressive disclosure metadata for routing). + + + +**Consequences (testable):** +- Catalog includes entries for common patterns: `.cursor/rules/` (existing Cursor config), `terraform/` (infrastructure), `_bmad/` (BMAD framework), `package.json` (Node.js), `pyproject.toml` (Python), etc. +- Each entry specifies: pattern, what it indicates, and how it affects complexity scoring +- The AI uses the catalog as reference but can reason about patterns not in the catalog + +### 4.3 Dry-Run and Preview + +**Description:** Before writing any files, the AI-installer presents all proposed changes as unified diffs the user can review. A `--dry-run` flag produces the preview and exits without writing. Realizes UJ-1, UJ-2, UJ-3, UJ-4. + +**Functional Requirements:** + +#### FR-10: Unified diff preview + +All proposed file creations and modifications are presented as unified diffs before any write operation. + +**Consequences (testable):** +- New files show as full-content diffs (--- /dev/null, +++ b/path) +- The user sees exact content that would be written, not a summary +- Diffs are presented in a format compatible with standard diff tools + +#### FR-11: Dry-run mode + +When the AI-installer is invoked with a dry-run intent (or `setup.sh --ai --dry-run`), it performs full analysis and generates diffs but writes nothing to disk. The `--dry-run` flag is communicated to the AI skill via `.agents/.agentic-os-setup-context.json` (written by setup.sh). + +**Consequences (testable):** +- After dry-run, no new files exist on disk +- Dry-run output is identical to what would be shown before a real write +- User can redirect dry-run output to a file for team review +- The setup context file contains `"dry_run": true` when this flag is passed + +#### FR-12: Approval gate + +After presenting diffs, the AI-installer waits for explicit user approval before writing any files. + +**Consequences (testable):** +- AI does not write files until user confirms +- User can reject individual files while approving others +- User can request modifications to proposed content before approval + +### 4.4 Conflict Detection and Safety + +**Description:** The AI-installer detects potential conflicts with existing AI configurations and aborts or warns rather than silently overriding behavior. Realizes UJ-1, UJ-2, UJ-4. + +**Functional Requirements:** + +#### FR-13: Glob collision detection + +Before generating .cursor/rules/ files, the AI-installer scans existing .mdc files for glob patterns that would overlap with proposed rules. + +**Consequences (testable):** +- If a proposed rule's glob overlaps with an existing rule's glob, the AI reports the collision +- Collision report includes: the existing file, its glob, the proposed glob, and why they conflict +- On collision: AI proposes alternatives (narrower glob, different approach) or aborts that specific rule + +#### FR-14: Existing rule numbering respect + +When generating .cursor/rules/ files in a repo with existing numbered rules (0XX-9XX convention), the AI-installer appends to the next available number in the appropriate band. + +**Consequences (testable):** +- If existing rules use 800-805, new rule is numbered 806 or higher (not 800) +- The band is determined by rule type (workflow rules → 8XX) +- Never renumbers or moves existing rule files + +#### FR-15: Non-destructive file policy + +The AI-installer NEVER modifies or deletes files it did not create, with one controlled exception: `.gitignore` receives an append-only managed block (FR-22). AGENTS.md may be extended via managed block append (FR-20). No other user files are modified. + +**Consequences (testable):** +- Existing .cursor/rules/ files are never modified +- Existing CLAUDE.md is never modified; AI creates `CLAUDE-agentic-os.md` as a companion file instead +- Existing .clinerules is never modified; AI creates `.clinerules-agentic-os` as a companion file instead +- If user has a hand-written AGENTS.md, the AI extends it with a managed block (never replaces user content above the block) +- `.gitignore` is appended with a delimited block (never replaces existing entries) +- No user file content is ever deleted or rewritten by the setup process + +#### FR-16: Framework coexistence detection + +When the AI-installer detects an existing agent framework (_bmad/, or similar), it defers persona ownership and generates only cross-reference and structural rules. + +**Consequences (testable):** +- If `_bmad/` directory exists, AI does NOT generate persona routing rules +- Generated rules are limited to: scope isolation, cross-reference enforcement, naming patterns +- The AI explains what it's deferring and why + +### 4.5 Runtime Adapters + +**Description:** The AI-installer translates configuration intent into the native format of each targeted AI runtime, producing semantically equivalent but syntactically different output per tool. Realizes UJ-1, UJ-2, UJ-3, UJ-4. + +**Functional Requirements:** + +#### FR-17: Claude Code adapter + +Generates CLAUDE.md with persona routing, execution rules, and quality gates formatted for Claude Code's instruction-following model. + +**Consequences (testable):** +- Output follows Claude Code's CLAUDE.md conventions (sections, headers, markdown formatting) +- References AGENTS.md for persona definitions +- Includes folder-specific behavior routing + +#### FR-18: Cursor adapter + +Generates .cursor/rules/NNN-agentic-os.mdc with proper YAML frontmatter (description, globs, alwaysApply) formatted for Cursor's rule system. + +**Consequences (testable):** +- Output includes valid YAML frontmatter with description and globs fields +- Glob patterns are specific to detected concern domains (not catch-all `*`) +- Rule file is numbered according to existing convention (or starts at 900 if no convention detected) + +#### FR-19: Cline adapter + +Generates .clinerules or equivalent Cline configuration expressing the same behavioral intent. + +**Consequences (testable):** +- Output follows Cline's expected configuration format +- Behavioral intent is semantically equivalent to Claude and Cursor outputs +- References shared AGENTS.md where applicable + +#### FR-20: Antigravity adapter + +Generates or augments AGENTS.md to serve as Antigravity's primary instruction file. Realizes UJ-4. + +**Consequences (testable):** +- AGENTS.md includes all persona routing and behavioral rules +- Format is compatible with Antigravity's AGENTS.md parsing +- If AGENTS.md already exists (from classic setup or user-written), extends with a managed block rather than replacing +- Existing user-written content above the managed block is never modified +- Managed block markers clearly delimit agentic-os sections from user content + +### 4.6 Installation Manifest + +**Description:** The AI-installer maintains a manifest of all files it created, enabling clean uninstall and safe re-run detection. Realizes UJ-1. + +**Functional Requirements:** + +#### FR-21: Manifest tracking + +Every file created by the AI-installer is recorded in `.agents/.agentic-os-manifest.json` with path, creation date, and content hash. + +**Consequences (testable):** +- After setup, manifest contains entries for every generated file +- Each entry has: `path`, `created_at`, `content_hash` +- Manifest file itself is gitignored by default + +#### FR-22: Gitignore management + +Generated files are added to .gitignore by default. A `--track` flag opts into version-controlling generated config. + +**Consequences (testable):** +- Without `--track`: all generated file paths are appended to .gitignore under an `# agentic-os generated` comment block +- With `--track`: generated files are NOT gitignored +- The gitignore block is clearly delimited for clean removal + +### 4.7 Documentation Updates + +**Description:** The feature requires updates to README.md to document the new `--ai` setup path, and a new CONTRIBUTING.md file to guide contributors working on the AI-installer skill, signal catalog, templates, and adapters. Realizes UJ-3 (discoverability), UJ-1 (understanding what happened). + +**Functional Requirements:** + +#### FR-23: README update + +README.md must be updated to document the AI-assisted setup path alongside the existing Quick Start instructions. + +**Consequences (testable):** +- Quick Start section includes a step for `--ai` setup as an alternative to classic mode +- Architecture mermaid diagram updated to show AI-installer skill as a component +- A new mermaid flow diagram shows the AI-assisted setup flow (setup.sh --ai → skill dropped → AI invoked → scan → classify → propose → approve → generate) with mode indicators (first-run, dry-run) +- Agent Compatibility section lists Cursor, Cline, and Antigravity alongside existing runtimes +- File System Layout shows the `.agents/skills/agentic-os-setup/` directory +- A "Setup Modes" section explains classic vs AI-assisted with clear when-to-use guidance + +#### FR-24: CONTRIBUTING.md + +A CONTRIBUTING.md file must exist at repo root describing how to contribute to the project, with specific guidance for the AI-installer skill components. + +**Consequences (testable):** +- File exists at repo root as `CONTRIBUTING.md` +- Covers: how to add signals to the catalog, how to add rule templates, how to add runtime adapters +- Includes: development workflow (fork, branch, test, PR) +- References: license (CC BY-NC-SA 4.0), code of conduct expectations +- Documents: how to test changes across runtimes (manual testing protocol) +- Lists: what constitutes a good PR for this project (signal + template + adapter together) + +### 4.8 Test Infrastructure + +**Description:** The project includes test repos (real directory structures mimicking UJ-1 through UJ-4), a shell-based test runner for setup.sh flag validation, and a Python-based test runner for generated content validation. Enables automated regression testing. Realizes SM-2, SM-3, SM-4, SM-5. + +**Functional Requirements:** + +#### FR-27: Test repo fixtures + +The project includes real directory structure fixtures in `examples/` that mimic each user journey's repo structure. + +**Consequences (testable):** +- `examples/uj-1-node-monorepo/` contains a realistic Node.js monorepo structure (package.json with workspaces, .cursor/rules/ with 3 existing files, src/, tests/) +- `examples/uj-2-architect-monorepo/` contains a complex multi-concern structure (Designs/, Operations/, Team-Workitems/, Infrastructure/, _bmad/, .cursor/rules/ with 10+ files) +- `examples/uj-3-flask-simple/` contains a simple Flask project (src/, tests/, requirements.txt, no AI config) +- `examples/uj-4-rust-antigravity/` contains a Rust workspace (Cargo.toml with workspace, 3 crate dirs, existing AGENTS.md) +- Each fixture is a self-contained directory that setup.sh --ai --target can be invoked against + +#### FR-28: Shell test runner + +A POSIX-compatible shell test script validates setup.sh flag parsing, mode routing, and remove logic. + +**Consequences (testable):** +- `tests/test_setup.sh` exists and is executable +- Tests validate: --help output, --ai flag routing, --runtime validation (valid and invalid), --remove with/without manifest, --target with valid/invalid paths, --auto requiring --runtime, flag combinations (--ai --dry-run --runtime, etc.) +- Tests run without external dependencies beyond sh, jq, and standard POSIX tools +- Tests produce pass/fail output with clear failure messages +- Test results are written to `tests/results/shell/report.txt` (plaintext summary) + +#### FR-29: Python content validator + +A pytest-based test suite validates that generated content (from running the AI skill against test fixtures) meets structural and semantic requirements. + +**Consequences (testable):** +- `tests/test_content.py` exists with pytest test cases +- `pytest.ini` configures test paths and JUnit XML output (`tests/results/python/report.xml`) +- `tests/conftest.py` generates a plaintext report (`tests/results/python/report.txt`) via session hook +- Tests validate: manifest JSON schema correctness, .mdc YAML frontmatter validity, glob specificity (no bare `*`), managed block marker syntax, gitignore block structure, numbering respect (no renumbering existing files) +- Tests can run against pre-generated output in `tests/results/python/` or generate fresh output +- Tests cover 5 scenarios: simple project, complex project, existing AI config (collision detection), framework coexistence (BMAD deferral), clean uninstall verification +- Python test dependencies: `pytest`, `pyyaml` + +#### FR-30: Test results gitignored + +Test output artifacts are gitignored to prevent generated content from polluting the repository. + +**Consequences (testable):** +- `tests/results/` directory exists in .gitignore +- Shell tests write to `tests/results/shell/report.txt` +- Python tests write to `tests/results/python/report.xml` (JUnit XML) and `tests/results/python/report.txt` (plaintext) +- Running tests does not modify any tracked files + +## 5. Non-Goals (Explicit) + +- **Re-run with delta merging** — Phase 2. V1 supports first-run and dry-run only; re-run requires managed blocks and checksum infrastructure. +- **Team-scoped context isolation** — Phase 2. Requires folder-to-team mapping that needs UX design. +- **BMAD deep integration** — V1 defers to BMAD when detected. Full integration (reading BMAD personas, extending them) is Phase 2. +- **Relationship graph visualization** — Phase 3. Useful but not load-bearing for setup. +- **MCP/Azure DevOps integration detection** — Phase 3. Beyond filesystem signals. +- **Dynamic/ephemeral config generation** — Phase 4 (first-principles vision). V1 generates static files. +- **CI/CD headless mode** — Partially addressed by `--auto` flag for single-runtime unattended runs. Full CI/CD integration (multi-stage pipelines, artifact caching) remains future scope. +- **Runtimes beyond v1 set** — GitHub Copilot, Kiro, Codex, Pi are future phases. +- **Modifying existing user files** — Never, except controlled append-only managed blocks on `.gitignore` (FR-22) and AGENTS.md (FR-20). No other user files are modified. + +## 6. MVP Scope + +### 6.1 In Scope + +- `setup.sh --ai` flag with `--runtime`, `--dry-run`, `--remove`, `--track`, `--target`, `--auto` options +- AI-installer skill (SKILL.md) with reasoning framework, signal catalog, rule templates +- 4-tier complexity detection with user-facing proposal +- Config generation for Claude Code, Cursor, Cline, Antigravity +- Unified diff preview before any write +- Explicit approval gate (bypassed in auto mode) +- Auto-approval mode with explicit runtime requirement +- Target directory support for running against any repo +- Glob collision detection (scan + abort on conflict; hard fail in auto mode) +- Existing rule numbering respect +- Framework coexistence detection (defer to BMAD if present) +- Non-destructive file policy (never modify user files) +- Installation manifest for clean uninstall +- Gitignore management (default: ignore generated files) +- Discoverability message in classic setup output +- Test repo fixtures (4 UJ-based directory structures) +- Automated test suite (shell + Python, 5 scenarios) + +### 6.2 Out of Scope for MVP + +- Re-run / update mode — deferred to Phase 2. [NOTE FOR PM] Users will need to `--remove` and re-run for now. +- Managed blocks with checksum guards — Phase 2 prerequisite for safe re-run. +- Team isolation — Phase 2. Multi-team repos get basic config without team boundaries. +- Relationship graph persistence — Phase 3. Relationships are computed per-run, not saved. + +## 7. Success Metrics + +Note: This is an open-source CLI tool with no telemetry. Metrics are observable via GitHub issues, PR feedback, and manual testing — not automated analytics. + +**Primary (observable via GitHub engagement + manual testing)** +- **SM-1**: Adoption signal — `--ai` is mentioned in issues/discussions as the preferred setup path by users who try it. Feature is referenced in community forks. Validates FR-1, FR-4. +- **SM-2**: Setup completion — manual testing across all 4 complexity tiers completes without user needing to abort due to poor proposals. Users who file issues report successful runs, not broken states. Validates FR-10, FR-12, FR-7. +- **SM-3**: Clean first-run — testing on repos with no existing AI config produces zero glob collisions or conflict aborts. Validates FR-13, FR-14. + +**Secondary (observable via testing protocol)** +- **SM-4**: Uninstall confidence — `--remove` on any completed setup leaves zero leftover artifacts (verifiable in manual test protocol). Validates FR-3, FR-21. +- **SM-5**: Multi-runtime consistency — generated configs for the same repo express semantically equivalent intent across Claude, Cursor, Cline, and Antigravity (verifiable by comparing outputs). Validates FR-17, FR-18, FR-19, FR-20. + +**Counter-metrics (design constraints, not measured)** +- **SM-C1**: Generated file count — should NOT increase over time. More files ≠ better. Tier-gating exists to prevent bloat. Counterbalances SM-2. +- **SM-C2**: False confidence — users should NOT trust generated config blindly. Dry-run exists to encourage review. Counterbalances SM-1. + +## 8. Open Questions + +1. ~~Should the AI-installer skill be a single SKILL.md or split into sub-files?~~ **RESOLVED** — Architecture Decision 3: Single SKILL.md as orchestrator with modular supporting files (catalog.md, templates/, adapters/, examples/). +2. What's the exact instruction the user types in each runtime? ("run setup" vs a slash command vs natural language) — To be defined per-adapter during implementation. +3. ~~How does the signal catalog stay up-to-date?~~ **RESOLVED** — CONTRIBUTING.md defines the community contribution path for adding signals. +4. ~~Should denied relationships be persisted?~~ **RESOLVED** — Architecture Decision 6: Manifest stores `denied_relationships` array to prevent re-proposal across sessions. +5. What's the minimum set of signals for each complexity tier? (Need to avoid over-classifying simple repos as Multi) — To be calibrated during catalog authoring and testing. + +## 9. Delivery + +The pull request template for this feature is at `pull-request.md` in this directory. It uses the PRD vision and motivation sections as the basis for PR messaging and documents the BMad Method planning process that produced these artifacts. + +## 10. Assumptions Index + +- [ASSUMPTION from §4.1] Classic `setup.sh` output can be modified to add the discoverability line without breaking existing workflows +- [ASSUMPTION from §4.2] AI runtimes can execute a SKILL.md by reading it as context/instructions without specialized plugin infrastructure +- [ASSUMPTION from §4.4] Cursor does not have built-in conflict resolution for overlapping .mdc globs — collisions are truly silent +- [ASSUMPTION from §4.5] Cline's .clinerules format is stable and documented enough to generate programmatically. **Validation plan:** Before implementing Story 4.3, verify current .clinerules format against Cline's official documentation/source. If format is unstable or undocumented, fallback: generate a generic markdown instruction file that Cline can read as context, and document the limitation in the adapter. +- [ASSUMPTION from §4.6] A JSON manifest is preferable to alternative tracking methods (e.g., marker comments in files) diff --git a/_bmad-output/prd-ai-assisted-setup-2026-06-20/pull-request.md b/_bmad-output/prd-ai-assisted-setup-2026-06-20/pull-request.md new file mode 100644 index 0000000..338fc7e --- /dev/null +++ b/_bmad-output/prd-ai-assisted-setup-2026-06-20/pull-request.md @@ -0,0 +1,175 @@ +# Pull Request: AI-Assisted Complex Repo Auto-Setup + +## Title + +feat: Add AI-assisted setup path for complex repos (`setup.sh --ai`) + +## Summary + +Adds an AI-installer skill that enables intelligent, complexity-aware setup for existing repositories. Instead of the current one-size-fits-all questionnaire, users can run `setup.sh --ai` to bootstrap an AI skill that analyzes their repo structure, classifies its complexity (Zero/Simple/Multi/Complex), proposes configuration proportional to detected needs, previews everything as unified diffs, and writes only after explicit approval. + +**The paradigm shift:** Setup is no longer a script that asks questions and writes files. Setup IS the AI reading the repo and configuring itself. The script becomes a bootstrap; the AI becomes the installer. + +## Motivation + +Agentic-os today assumes a greenfield personal workspace. But most developers who discover it already have a project — often a complex one with multiple concerns, existing AI configurations, team structures, and cross-domain relationships. They cannot use agentic-os without manually figuring out how to map their repo into the OS's expectations. + +This feature makes agentic-os smart enough to meet users where they are — from a student's Flask project to an architect's multi-team monorepo. + +## What's Included + +### New files + +- `.agents/skills/agentic-os-setup/SKILL.md` — Orchestrator (mode detection, scanning, classification, proposal, approval, write protocol) +- `.agents/skills/agentic-os-setup/agents/openai.yaml` — Agent Skills open standard metadata (routing, description) +- `.agents/skills/agentic-os-setup/catalog.md` — Signal catalog (15+ filesystem patterns and their meanings) +- `.agents/skills/agentic-os-setup/templates/` — Rule templates (persona-routing, scope-isolation, cross-reference, naming-enforcement, quality-gates) +- `.agents/skills/agentic-os-setup/adapters/` — Runtime adapters (claude.md, cursor.md, cline.md, antigravity.md) +- `.agents/skills/agentic-os-setup/examples/` — Calibration examples (simple-output.md, complex-output.md) +- `CONTRIBUTING.md` — Contributor guide for extending signals, templates, and adapters + +### New files (test infrastructure) + +- `pytest.ini` — Pytest configuration (test paths, JUnit XML output to `tests/results/python/report.xml`) +- `tests/test_setup.sh` — Shell test runner (29 tests, validates flag parsing and routing) +- `tests/test_content.py` — Python content validator (24 tests, validates structure and schema) +- `tests/conftest.py` — Pytest hook for plaintext report generation (`tests/results/python/report.txt`) +- `examples/uj-1-node-monorepo/` — Test fixture: Node.js monorepo with 3 Cursor rules +- `examples/uj-2-architect-monorepo/` — Test fixture: Complex multi-concern with BMAD, 10 Cursor rules +- `examples/uj-3-flask-simple/` — Test fixture: Simple Flask project, no AI config +- `examples/uj-4-rust-antigravity/` — Test fixture: Rust workspace with existing AGENTS.md + +### Modified files + +- `setup.sh` — Adds `--ai`, `--runtime`, `--dry-run`, `--remove`, `--track`, `--target`, `--auto`, `--help` flags +- `README.md` — Documents AI-assisted setup path, updated architecture diagram, new mermaid flow diagram, runtime compatibility +- `.gitignore` — Adds `tests/results/` exclusion + +## Key Design Decisions + +1. **AI-as-installer paradigm** — The shell script bootstraps; the AI executes. All intelligence lives in SKILL.md. +2. **4-tier complexity model** — Zero/Simple/Multi/Complex gates output volume proportionally. +3. **Non-destructive by design** — Never modifies user files. Creates companion files or append-only managed blocks. +4. **Multi-runtime support** — Claude Code, Cursor, Cline, Antigravity. Same intent, native format per tool. +5. **Backwards compatible** — `setup.sh` without flags = unchanged behavior. Zero regression risk. +6. **Clean uninstall** — Manifest-tracked files, `setup.sh --remove` restores repo to pre-setup state. +7. **Target directory** — `--target ` enables running against any repo without cd. setup.sh bootstraps the workspace (copies skills, workflows, dirs) into the target, so the AI skill runs locally with no cross-repo references. +8. **Auto-approval mode** — `--auto` skips interactive approval (requires explicit `--runtime`). Shows preview then writes. +9. **Dual test strategy** — Shell tests for CLI behavior, Python/pytest for content validation. Real repo fixtures for UJ-1 through UJ-4. + +## Planning Methodology + +This feature was planned using the **BMad Method** (Build Method for AI-assisted Development) — a structured workflow that produces traceable artifacts from brainstorming through implementation readiness: + +- **Brainstorming** — 28 ideas across 3 phases, evaluated with structured reasoning frameworks +- **PRD** — 31 functional requirements, 7 non-functional requirements, 4 user journeys, success metrics +- **Architecture** — 11 decisions, FR coverage matrix, interface contracts for parallel development +- **Epics & Stories** — 7 epics, 27 stories with Given/When/Then acceptance criteria +- **Adversarial Review** — 15 findings identified and resolved before implementation +- **Implementation Readiness** — 100% FR coverage validated, 0 critical issues + +Planning artifacts are in `_bmad-output/prd-ai-assisted-setup-2026-06-20/`. + +## Supported Runtimes + +Valid `--runtime` values: `claude`, `cursor`, `cline`, `antigravity` + +| Runtime ID | Tool | Output format | Pre-existing behavior | +|-----------|------|--------------|----------------------| +| `claude` | Claude Code | CLAUDE.md (or CLAUDE-agentic-os.md if exists) | Companion file | +| `cursor` | Cursor | .cursor/rules/NNN-agentic-os.mdc | New numbered file | +| `cline` | Cline | .clinerules (or .clinerules-agentic-os if exists) | Companion file | +| `antigravity` | Antigravity | AGENTS.md | Managed block append | + +Adding a new runtime requires: a new adapter file in `adapters/`, an update to `VALID_RUNTIMES` in setup.sh, and a row in this table. + +## How to Test + +```bash +# AI-assisted setup (all runtimes) +./setup.sh --ai + +# Target specific runtimes +./setup.sh --ai --runtime claude,cursor + +# Preview without writing +./setup.sh --ai --dry-run + +# Run against a different directory (bootstraps workspace + skill into target) +./setup.sh --ai --target ./my-project --runtime claude + +# Auto-approval mode (unattended, requires explicit --runtime) +./setup.sh --ai --auto --runtime claude,cursor + +# Clean removal +./setup.sh --remove + +# Classic setup (unchanged) +./setup.sh + +# Run tests +sh tests/test_setup.sh +pytest tests/test_content.py +``` + +Then invoke the AI skill in your runtime of choice and verify: +- Correct complexity tier detected +- Appropriate output proposed (not over/under-generating) +- Dry-run shows accurate diffs +- No conflicts with existing configs +- Generated files are valid for their target runtime + +## Verification Status + +**Runtimes tested:** +- ✅ **Claude Code** — Complex tier repo (BMAD, 54 existing skills, 7 concern folders). Generated: AGENTS.md (full behavioral instructions), GOALS.md (AI-inferred), CLAUDE-agentic-os.md (companion). BMAD persona deferral working. Track vs gitignore decision correct. +- ✅ **Cursor** — Same repo. Generated 4 `.cursor/rules/` files (806-809) with proper numbering, specific globs, no collisions with existing 800-805. BMAD deferral, scope isolation, naming, cross-refs, quality gates. + +**Unit tests:** +- ✅ Shell tests: 29/29 passed (flag parsing, routing, --remove, --target, --auto) +- ✅ Python tests: 24/24 passed (manifest schema, .mdc frontmatter, glob specificity, managed blocks, numbering) + +**Not yet tested:** Cline, Antigravity (no test environment available — requesting reviewer validation). + +## Example Output (Complex Tier) + +Tested against a multi-concern documentation monorepo with BMAD framework, 54 existing skills, `.cursor/rules/`, and 7 concern folders: + +``` +Classification: Complex tier (driven by _bmad/ framework presence, 7 concern folders, 4 AI config systems) + +Files written: + AGENTS.md — 4.1 KB — Workspace behavioral rules, scope boundaries, workflows reference + GOALS.md — 2.4 KB — AI-inferred professional goals and priorities + CLAUDE-agentic-os.md — 2.4 KB — Companion config (scope isolation, naming, cross-refs) + .agents/.agentic-os-manifest.json — 764 B — Manifest for tracking/removal + +Gitignore: Updated with managed block (generated files are gitignored by default). +Framework coexistence: Persona routing deferred to BMAD. +``` + +## Reviewer Ask + +Beyond validating the documented test cases, we'd appreciate reviewers testing against their own real-world repos — especially: +- Repos with existing AI configurations (Cursor rules, CLAUDE.md, .clinerules) +- Monorepos with workspaces (npm, Cargo, Go) +- Repos with non-standard structures not covered by the signal catalog +- Edge cases: empty repos, repos with only binary files, very large repos + +Please report unexpected classifications, missing signals, or over/under-generation in the review. + +## Dependencies + +- `jq` required for `--remove` manifest parsing (setup.sh checks and guides if missing) +- No other external dependencies + +## Out of Scope (Phase 2+) + +- Re-run with delta merging (requires managed block checksum infrastructure) +- Team-scoped context isolation +- BMAD deep integration (v1 defers to BMAD when detected) +- Runtimes beyond v1 set (Copilot, Kiro, Codex, Pi) + +## License + +All contributions under [CC BY-NC-SA 4.0](LICENSE), consistent with the existing project license. diff --git a/examples/uj-1-node-monorepo/.agents/skills/README.md b/examples/uj-1-node-monorepo/.agents/skills/README.md new file mode 100644 index 0000000..aa12943 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/README.md @@ -0,0 +1,35 @@ +# Skills (Canonical) + +This directory is the canonical runtime skill location for Codex/OpenAI-style skills. + +## Layout + +- One folder per skill +- Each skill folder must contain `SKILL.md` +- Optional agent-specific metadata can live at `agents/openai.yaml` +- Recommended: include `## When to Use` and `## When Not to Use` sections + +Example: + +``` +.agents/skills/verification/SKILL.md +.agents/skills/verification/agents/openai.yaml +.agents/skills/tdd/SKILL.md +.agents/skills/linear-issue-sync/SKILL.md +``` + +## Source of Truth + +Runtime skill packs in `.agents/skills/` are the source of truth. + +Edit skills directly in this directory, then validate: + +```bash +python scripts/validate_skills.py +``` + +If using Claude-specific skill discovery, this repo bridges: + +```bash +.claude/skills -> ../.agents/skills +``` diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/SKILL.md new file mode 100644 index 0000000..cae9a0b --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/SKILL.md @@ -0,0 +1,380 @@ +# Agentic-OS AI-Assisted Setup + +## Purpose + +Intelligent, complexity-aware setup for agentic-os. Performs two jobs: + +1. **Workspace bootstrapping** — Creates the agentic-os workspace structure (directories, AGENTS.md, GOALS.md, BACKLOG.md, symlinks, skills, workflows) in the target repo, auto-populating GOALS.md from repo analysis instead of a questionnaire. +2. **Configuration generation** — Scans repo structure, classifies complexity, proposes runtime-specific configuration proportional to detected needs, previews as unified diffs, and writes only after approval. + +Both jobs run in sequence. The AI replaces the classic setup questionnaire entirely — it infers what the questionnaire would have asked from the repo's own signals. + +## Mode Detection + +Before beginning, check for the context bridge file at `.agents/.agentic-os-setup-context.json`. If present, read it to determine: +- `runtimes`: which runtime adapters to generate for +- `dry_run`: if true, perform full analysis and proposal but write zero files +- `track`: if true, skip gitignore management (files will be committed) +- `auto`: if true, show the diff preview but skip the approval gate — write immediately after presenting diffs + +Note: By the time you run, `setup.sh` has already bootstrapped the workspace (copied skills, workflows, dirs, BACKLOG.md, symlinks into this repo). Your job is the smart parts: scan, classify, infer GOALS.md, generate runtime config, and handle files that need cross-referencing (CLAUDE.md, AGENTS.md, etc.). + +If the context bridge file is not present, ask the user which runtimes they want and whether this is a dry run. + +Check for an existing manifest at `.agents/.agentic-os-manifest.json`: +- If manifest exists: this is a **re-run**. Phase 1 does not support re-run — inform the user that re-run with delta merging is planned for Phase 2, and suggest `setup.sh --remove` followed by a fresh `--ai` run if they want to regenerate. +- If no manifest: this is a **first-run**. Proceed with workspace bootstrapping, then scanning. + +## AI Responsibilities (Post-Bootstrap) + +`setup.sh` has already handled the "dumb" copying: directories, BACKLOG.md, Workflows/, .agents/skills/, symlinks, .gitignore template. Your job is the smart inference and generation: + +### 1. Create or update AGENTS.md + +If `AGENTS.md` does NOT exist: copy the standard agentic-os AGENTS.md from `.agents/skills/agentic-os-setup/` reference (the AI should generate a fresh AGENTS.md following the agentic-os template structure — workspace layout, task format, categories, priority levels, backlog processing, daily guidance, skills reference, workflows reference). + +If `AGENTS.md` already exists: extend it with a managed block containing agentic-os behavioral rules (scope isolation, cross-references, etc.) — same as Antigravity adapter behavior. + +### 2. Create or update AI tool wrapper files + +For each targeted runtime, create the appropriate wrapper file if it doesn't exist: +- **Claude**: `CLAUDE.md` — if missing, create with `@AGENTS.md`. If exists, create `CLAUDE-agentic-os.md` companion. +- **Codex**: `CODEX.md` — if missing, create with reference to AGENTS.md + skill location. +- **Pi**: `PI.md` — if missing, create with reference to AGENTS.md + skill location. +- **OpenClaw**: `OPENCLAW.md` — if missing, create with reference to AGENTS.md + skill location. + +### 3. Auto-generate GOALS.md + +Instead of asking a questionnaire, infer goals from repo signals: + +| Classic Question | AI Inference Source | +|-----------------|-------------------| +| "What's your current role?" | README, CONTRIBUTING, package.json author, git config, folder structure purpose | +| "What's your professional vision?" | Repo scope: what domain it serves, what it's building toward | +| "12-month success criteria?" | Open issues, roadmap files, TODO/BACKLOG, README goals section | +| "This quarter objectives?" | Recent commits focus, active branches, work-in-progress indicators | +| "Top 3 priorities?" | Most-edited directories, recent activity, README priority sections | + +Write `GOALS.md` using the standard template structure. Mark inferred sections with `[AI-inferred — refine as needed]`. Leave unknowable fields empty with ``. + +### 4. Generate runtime-specific configuration + +This is the classification + proposal flow (Scanning → Classification → Proposal → Preview → Write) described in the sections below. + +--- + +## Scanning Protocol + +### What to Read + +Scan the repository filesystem for structural signals: + +1. **Top-level directories** — list all directories at root (ignore hidden dirs except `.cursor/`, `.claude/`, `.cline/`) +2. **Config files at root** — package.json, pyproject.toml, Cargo.toml, go.mod, Makefile, docker-compose.yml, terraform/, .github/ +3. **Existing AI configuration** — .cursor/rules/*.mdc, CLAUDE.md, .clinerules, AGENTS.md, .claude/ +4. **Agent frameworks** — _bmad/, .agents/ contents +5. **Documentation** — docs/, README.md, CONTRIBUTING.md +6. **Team indicators** — directories containing "team", group-based folder structures + +### What NOT to Read + +- File contents beyond config/manifest files (respect privacy — NFR-5) +- Binary files +- node_modules/, .git/, build artifacts, vendor/ +- Any file > 100KB + +### Signal Matching + +Cross-reference detected patterns against `catalog.md`. For each matched signal, note: +- Which complexity dimension it contributes to +- What setup implications it carries +- Any coexistence behavior required + +## Classification Logic + +Use the **highest-dimension-wins** scoring algorithm: + +### Dimensions + +| Dimension | Zero | Simple | Multi | Complex | +|-----------|------|--------|-------|---------| +| Top-level concern folders | 0 | 1-2 | 3-4 | 5+ | +| Existing AI config files | 0 | 0-1 | 2-3 | 4+ | +| Team/group indicators | 0 | 0 | 1 | 2+ | +| Cross-domain references detected | 0 | 0 | 1 | 2+ | +| Agent framework present (_bmad/, etc.) | No | No | No | Yes | + +### Algorithm + +1. For each dimension, map the detected count to a tier (Zero=0, Simple=1, Multi=2, Complex=3) +2. Take the maximum score across all dimensions +3. If max = 0 → **Zero** tier; 1 → **Simple**; 2 → **Multi**; 3 → **Complex** +4. Present the classification WITH the scoring breakdown so the user can challenge it + +### Override Protocol + +Always propose the classification with rationale. The user can override up or down. Respect the override without argument. + +### Calibration + +- A repo with `_bmad/` is automatically Complex (framework presence is a strong signal) +- A repo with only `src/` and `tests/` should never exceed Simple regardless of file count +- See `examples/simple-output.md` and `examples/complex-output.md` for calibration + +## Proposal Generation + +Based on the classified tier and detected signals, assemble a configuration proposal: + +### Tier Output Expectations + +| Tier | What Gets Generated | +|------|-------------------| +| Zero | Nothing — repo is empty. Suggest running classic `setup.sh` instead. | +| Simple | 1 config file per targeted runtime. Minimal: basic project context, no persona routing. | +| Multi | Config files per runtime + AGENTS.md with persona definitions. Persona routing, scope isolation. | +| Complex | Full output: AGENTS.md, GOALS.md (if none exists), config files with persona routing, scope isolation, cross-reference enforcement, quality gates. | + +### Assembly Process + +1. Select applicable templates from `templates/` based on tier and detected signals (check each template's "When to Use" section) +2. Fill template placeholders with detected values (domains, personas, relationships) +3. Format output per runtime using the corresponding adapter in `adapters/` +4. Collect all proposed files into a unified proposal + +### Relationship Discovery + +- **Manifest-declared relationships** (found in package.json workspaces, go.work, etc.) are trusted — include them directly +- **AI-inferred relationships** (e.g., folder naming patterns suggest linkage) require user confirmation before inclusion in generated rules + +## Framework Coexistence + +When `_bmad/` directory is detected during scanning: +- Do NOT generate persona routing rules (defer persona ownership to BMAD) +- Limit generated rules to: scope isolation, cross-reference enforcement, naming patterns +- Explain what you're deferring and why in the proposal + +When other AI configs exist (.cursor/rules/, CLAUDE.md, .clinerules): +- Do NOT modify or replace them +- Generate agentic-os rules as additive companion files (see adapter specs for pre-existing file behavior) +- Check for glob collisions with existing .cursor/rules/ before proposing new ones + +## Diff Preview Protocol + +All proposed changes MUST be presented as unified diffs before any files are written. + +### New Files + +Present as a diff against `/dev/null`: + +```diff +--- /dev/null ++++ b/CLAUDE.md +@@ -0,0 +1,25 @@ ++# Project Context ++ ++{full file content with + prefix on each line} +``` + +### Extensions to Existing Files + +For files being extended (e.g., AGENTS.md managed block append, .gitignore append): + +```diff +--- a/.gitignore ++++ b/.gitignore +@@ -42,0 +43,5 @@ ++# === AGENTIC-OS GENERATED (do not edit this block) === ++CLAUDE.md ++.agents/.agentic-os-manifest.json ++# === END AGENTIC-OS GENERATED === +``` + +### Presentation Rules + +1. Show ALL proposed files in a single diff block (or clearly labeled separate blocks) +2. Use standard unified diff format compatible with `patch` and `git apply` +3. Include file paths relative to repo root +4. For multi-file proposals, separate each file's diff with a blank line +5. After presenting diffs, clearly state: "These are the proposed changes. Approve all, approve selectively, or reject?" + +### Selective Approval + +The user can: +- **Approve all** — write everything as proposed +- **Approve selectively** — specify which files to write (e.g., "write CLAUDE.md and the manifest but skip the Cursor rules") +- **Reject** — write nothing, end the session + +Respect the user's selection exactly. Only write approved files. + +### Auto-Approval Mode + +When `auto: true` is set in the context bridge: + +1. Present all diffs exactly as in normal mode (for logging/audit) +2. **Do NOT wait for user approval** — proceed directly to writing +3. If conflict detection finds a collision: **FAIL with error** (do not silently overwrite). Print the conflict report and exit without writing any files. +4. If `dry_run` is also true: show diffs, write nothing (dry-run takes precedence over auto) + +Auto mode is designed for unattended execution where the user has pre-selected their runtimes via `--runtime`. It still shows what will be written but doesn't pause for confirmation. + +## Dry-Run Mode + +When dry-run is active (detected from context bridge `dry_run: true` or user states "dry run"): + +1. Execute the FULL workflow: scanning, classification, proposal generation +2. Present diffs exactly as in normal mode +3. **Write ZERO files to disk** +4. Do NOT create a manifest +5. Do NOT modify .gitignore +6. Clearly indicate at the start and end: "DRY RUN — no files will be written" + +The user gets full visibility into what WOULD happen, without any side effects. + +## Conflict Detection Protocol + +Before writing ANY file, perform these safety checks: + +### Cursor Glob Collision Detection + +When proposing `.cursor/rules/` files: + +1. List ALL existing `.mdc` files in `.cursor/rules/` +2. Parse YAML frontmatter of each to extract `globs` value +3. Compare each proposed glob against all existing globs +4. A collision exists if: + - Proposed glob is identical to an existing glob + - Proposed glob is a superset of an existing glob (e.g., `src/**/*` covers `src/components/**/*`) + - Proposed glob overlaps with an existing glob (shared file matches) + +**On collision:** +- Report: existing file name, its glob, proposed glob, and why they conflict +- Propose alternatives: narrower glob that avoids overlap, or skip that rule +- Never write a colliding rule without user approval of the alternative + +### Numbering Respect + +When generating Cursor `.mdc` files: +1. Scan existing files for their numeric prefixes +2. Identify the highest number in use +3. Use the next available number (e.g., if 805 exists, use 806) +4. NEVER renumber or move existing files +5. If no existing rules, default to 900-band + +### Non-Destructive File Policy + +**Core invariant:** Never modify or delete user files. + +**Exceptions (append-only managed blocks):** +- `.gitignore` — append a delimited block at the end (never edit existing lines) +- `AGENTS.md` — append a managed block at the end (never edit existing content above the block) + +**For all other existing files:** +- If the target path already exists and is NOT one of the append-only exceptions: create a companion file instead (see adapter specs for per-runtime behavior) +- If an existing managed block has been edited by the user (hash mismatch): warn and skip overwrite + +### Framework Coexistence Check + +When `_bmad/` is detected: +- Skip persona routing template entirely +- Explain in the proposal: "Persona routing deferred to BMAD framework (detected `_bmad/` directory)" +- Only generate: scope isolation, cross-reference enforcement, naming, quality gates + +## Write Protocol + +After the user approves the proposal (fully or selectively), write files following this exact sequence: + +### Write Sequence + +1. Create approved configuration files (CLAUDE.md, .cursor/rules/*.mdc, .clinerules, AGENTS.md extension) +2. Write the manifest (`.agents/.agentic-os-manifest.json`) +3. Update .gitignore (unless `--track` was specified) + +### Manifest Schema + +Write to `.agents/.agentic-os-manifest.json`: + +```json +{ + "version": "1.0.0", + "created_at": "", + "complexity_tier": "", + "runtimes_targeted": ["", ""], + "files": [ + { + "path": "", + "created_at": "", + "content_hash": "sha256:" + } + ], + "denied_relationships": [], + "detected_frameworks": [""] +} +``` + +**Field definitions:** +- `version` — Schema version (always "1.0.0" for Phase 1). Future phases add fields but never remove or rename existing ones (additive-only evolution). +- `created_at` — When the setup was run +- `complexity_tier` — The classified tier +- `runtimes_targeted` — Which runtimes were configured +- `files` — Every file created or modified by this run. Each entry has the file path, creation timestamp, and SHA-256 hash of content. +- `denied_relationships` — Relationships the user rejected during proposal (prevents re-proposal on future re-runs) +- `detected_frameworks` — Frameworks found during scanning (e.g., "bmad") + +**Important:** The manifest must include ALL generated files — this is what `setup.sh --remove` uses for clean uninstall. Missing entries = orphaned files on removal. + +### Gitignore Management + +**Default behavior** (when `--track` was NOT specified): + +Append a managed block at the end of `.gitignore`: + +```gitignore +# === AGENTIC-OS GENERATED (do not edit this block) === + +.agents/.agentic-os-manifest.json +# === END AGENTIC-OS GENERATED === +``` + +Rules: +- List every file path from the manifest's `files` array +- Include the manifest itself +- Always append at the end — never insert or modify existing gitignore content +- If `.gitignore` doesn't exist, create it with just the managed block +- The context bridge file (`.agents/.agentic-os-setup-context.json`) is NOT gitignored — it's ephemeral and deleted by `--remove` + +**When `--track` is specified:** +- Do NOT modify `.gitignore` +- Generated files will be committed to the repository +- This is intentional — the user wants the configuration shared with their team + +### Managed Block Specification + +For files that use managed blocks (AGENTS.md, .gitignore): + +**HTML-comment style** (for AGENTS.md and other markdown files): +``` + +{content} + +``` + +**Comment style** (for .gitignore and other non-markdown files): +``` +# === AGENTIC-OS GENERATED (do not edit this block) === +{content} +# === END AGENTIC-OS GENERATED === +``` + +**Hash computation:** +- Hash the content BETWEEN the markers (not including markers themselves) +- Use SHA-256 +- Store as hex string in the start marker +- Purpose: Phase 2 re-run can detect if user manually edited managed content + +### Post-Write Confirmation + +After writing all approved files: +1. Print a summary of what was written (file paths and sizes) +2. Confirm the manifest was created +3. Confirm gitignore status (updated or skipped due to --track) +4. Remind user: "To undo, run: setup.sh --remove" diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/antigravity.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/antigravity.md new file mode 100644 index 0000000..408abfc --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/antigravity.md @@ -0,0 +1,148 @@ +# Adapter: Antigravity + +## Purpose + +Describes how to format agentic-os generated output for Antigravity AI consumption via AGENTS.md. + +## File Path Convention + +- **Primary:** `AGENTS.md` at repo root +- **Behavior:** Always EXTEND existing content — never replace + +## Format Specification + +Antigravity reads AGENTS.md as its primary instruction file. It expects structured markdown with: + +- `##` headers for major sections (Personas, Rules, Standards) +- `###` headers for subsections (individual personas, rule groups) +- Tables for structured data (scope boundaries, relationships) +- Bullet lists for behavioral rules +- Imperative tone ("Focus on X", "Validate Y", "Never Z") + +## Constraints + +- Single file (AGENTS.md) +- Must coexist with user-written content +- Agentic-os content lives ONLY within managed block markers +- User content above the managed block is never touched +- If no AGENTS.md exists, create one entirely within managed markers + +## Managed Block Format + +```markdown + +{generated content goes here} + +``` + +- **Start marker:** `` +- **End marker:** `` +- **Hash:** SHA-256 of the content between markers (enables future re-run detection) +- **Placement:** Always at the END of AGENTS.md (below any user content) + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No AGENTS.md exists | Create AGENTS.md with content entirely within managed block | +| AGENTS.md exists without managed block | Append managed block at end of file | +| AGENTS.md exists with managed block | Replace managed block content (preserve everything outside) | +| User edited content inside managed block | Detect hash mismatch → warn user and skip overwrite | + +## Extend Semantics + +``` +AGENTS.md structure: +┌─────────────────────────────────────────────────────────────────┐ +│ [User's original content] │ ← never touched +│ ... │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ## Agentic-OS Generated Rules │ +│ {all generated content here} │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Examples + +### Example 1: New AGENTS.md (no existing file) + +```markdown + +## Agentic-OS Generated Rules + +### Project Context + +This is a Go microservices project with 3 services. + +### Quality Gates + +- Run `go test ./...` before completing work +- Run `golangci-lint run` for code quality +- Ensure new packages have corresponding test files + + +``` + +### Example 2: Extending existing AGENTS.md (Complex tier) + +User's existing content (preserved as-is): +```markdown +# Team Agents + +## Product Manager +Responsible for roadmap decisions... + +## Tech Lead +Responsible for architecture decisions... +``` + +After agentic-os extension: +```markdown +# Team Agents + +## Product Manager +Responsible for roadmap decisions... + +## Tech Lead +Responsible for architecture decisions... + + +## Agentic-OS Generated Rules + +### Personas + +#### Architect +**Scope:** `/Designs/` +**Focus:** System design, scalability, requirements traceability +**Behavioral rules:** +- Prioritize structural patterns over quick fixes +- Reference existing blueprints before proposing new structures + +#### Operations Specialist +**Scope:** `/Operations/` +**Focus:** Process efficiency, documentation completeness +**Behavioral rules:** +- Follow documentation standards +- Enforce cross-reference rules + +### Scope Boundaries + +| Domain | Isolated From | Rationale | +|--------|--------------|-----------| +| Designs/ | Operations/ | Architecture and HR are independent | +| Operations/ | Designs/ | Recruitment is independent of design | + +### Cross-References + +| Source | Target | Link Format | +|--------|--------|-------------| +| Operations/interviews/ | Operations/job-descriptions/ | `Job-ID: jd-*` | + + +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Antigravity as a runtime. It formats the assembled proposal (from templates) into AGENTS.md content within managed block markers, preserving any existing user content above the block. diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/claude.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/claude.md new file mode 100644 index 0000000..da09b94 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/claude.md @@ -0,0 +1,86 @@ +# Adapter: Claude Code + +## Purpose + +Describes how to format agentic-os generated output for Claude Code consumption. + +## File Path Convention + +- **Primary:** `CLAUDE.md` at repo root +- **If CLAUDE.md already exists:** Create `CLAUDE-agentic-os.md` as a companion file. Never modify the existing CLAUDE.md. + +## Format Specification + +Claude Code reads CLAUDE.md as a markdown file with freeform structure. Effective patterns: + +- Use `##` headers to organize sections (Persona Routing, Scope Isolation, Quality Gates, etc.) +- Bullet lists for rules and constraints +- Code blocks for commands and patterns +- Keep instructions direct and imperative ("Do X", "Never Y") + +## Constraints + +- Single file (no directory structure like Cursor) +- No frontmatter or metadata — pure markdown +- No glob-based routing — all rules apply globally (Claude Code doesn't have file-scoped rules) +- Rules must be self-describing (include "when editing in X" context inline) + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No CLAUDE.md exists | Create `CLAUDE.md` | +| CLAUDE.md exists | Create `CLAUDE-agentic-os.md` as companion. Add a note at top: "This file supplements the existing CLAUDE.md with agentic-os configuration." | + +Never modify an existing CLAUDE.md. + +## Examples + +### Example 1: Simple Tier (single-purpose project) + +```markdown +# Project Context + +This is a Python FastAPI project using pytest for testing. + +## Quality Gates + +Before completing work: +- Run tests: `pytest` +- Run type checking: `mypy src/` +- Run formatting: `ruff format --check .` + +## Project Structure + +- `src/` — Application source (FastAPI routes and models) +- `tests/` — Test files (pytest) +- `alembic/` — Database migrations +``` + +### Example 2: Multi Tier (multiple concerns) + +```markdown +# Agentic-OS Configuration + +## Persona Routing + +- **Backend Mode:** Triggered when editing `/backend/`. Focus on API design, data modeling, and performance. +- **Frontend Mode:** Triggered when editing `/frontend/`. Focus on component architecture, accessibility, and UX. +- **DevOps Mode:** Triggered when editing `/infra/`. Focus on reliability, security, and cost optimization. + +## Scope Isolation + +Do not cross-reference between isolated domains unless explicitly asked: +- `/backend/` and `/frontend/` have distinct conventions +- `/infra/` is independent from application code + +## Quality Gates + +- Backend: `cd backend && pytest && mypy .` +- Frontend: `cd frontend && npm test && npm run lint` +- Infrastructure: `cd infra && terraform validate` +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Claude Code as a runtime. It formats the assembled proposal (from templates) into Claude-appropriate markdown, respecting the constraints above. diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/cline.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/cline.md new file mode 100644 index 0000000..8ea84b8 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/cline.md @@ -0,0 +1,85 @@ +# Adapter: Cline + +## Purpose + +Describes how to format agentic-os generated output for Cline AI consumption. + +## File Path Convention + +- **Primary:** `.clinerules` at repo root +- **If `.clinerules` already exists:** Create `.clinerules-agentic-os` as a companion file. Never modify the existing `.clinerules`. + +## Format Specification + +Cline reads `.clinerules` as a plain text/markdown file containing behavioral instructions. Effective patterns: + +- Use `##` headers to organize sections +- Direct imperative rules ("Always X", "Never Y", "When doing Z, ensure W") +- Bullet lists for grouped rules +- Keep language concise and actionable + +## Constraints + +- Single file (no directory-based rule system like Cursor) +- No frontmatter or metadata +- No glob-based routing — all rules apply globally +- Rules must be self-describing (include path context inline where needed) +- Simpler format than Claude or Cursor — focus on behavioral directives + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No `.clinerules` exists | Create `.clinerules` | +| `.clinerules` exists | Create `.clinerules-agentic-os` as companion. Never modify existing file. | + +## Examples + +### Example 1: Simple Tier + +```markdown +# Project Rules + +## Quality Gates + +- Always run `npm test` before completing work +- Always run `npm run lint` before completing work +- New source files must have corresponding test files + +## Project Structure + +- Source code lives in `src/` +- Tests live in `tests/` +- Follow existing naming conventions +``` + +### Example 2: Multi Tier + +```markdown +# Agentic-OS Rules + +## Persona Routing + +When working in `/backend/`: +- Focus on API design, data modeling, and performance +- Follow Python conventions (PEP 8, type hints) + +When working in `/frontend/`: +- Focus on component architecture and accessibility +- Follow React/TypeScript conventions + +## Scope Isolation + +- Do not suggest content from `/backend/` when working in `/frontend/` +- Do not suggest content from `/frontend/` when working in `/backend/` +- Keep suggestions scoped to the current domain + +## Quality Gates + +- Backend: run `pytest` and `mypy` before completing work +- Frontend: run `npm test` and `npm run lint` before completing work +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Cline as a runtime. It formats the assembled proposal (from templates) into Cline-appropriate rules, respecting the single-file, directive-focused format. diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/cursor.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/cursor.md new file mode 100644 index 0000000..594925c --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/adapters/cursor.md @@ -0,0 +1,138 @@ +# Adapter: Cursor + +## Purpose + +Describes how to format agentic-os generated output for Cursor AI consumption via `.cursor/rules/` files. + +## File Path Convention + +- **Directory:** `.cursor/rules/` +- **Filename:** `NNN-agentic-os.mdc` or `NNN-agentic-os-{concern}.mdc` +- **Numbering:** Use the next available number in the appropriate band. Default to 900-band if no convention exists. If existing rules use a different band, append after the highest existing number. + +### Numbering Detection + +1. List all existing `.mdc` files in `.cursor/rules/` +2. Extract the numeric prefix from each filename +3. Identify the convention (e.g., 0XX=core, 1XX=tools, 8XX=workflow) +4. Place agentic-os rules in the highest available band (typically 900+) +5. Never renumber or move existing files + +## Format Specification + +Each `.mdc` file requires YAML frontmatter: + +```yaml +--- +description: Human-readable description of this rule's purpose +globs: path/to/files/**/*.ext +alwaysApply: true +--- +``` + +**Required fields:** +- `description` — Clear, concise explanation (shown in Cursor's rule list) +- `globs` — File patterns this rule applies to + +**Optional fields:** +- `alwaysApply` — Set to `true` when the rule should always be active for matched files + +**Body:** Markdown content after frontmatter contains the actual rules. + +## Constraints + +- Each file targets specific globs — rules are file-scoped, not global +- Globs must be specific: NEVER use `*` alone (too broad) +- One concern per file is preferred (persona routing separate from scope isolation) +- Keep individual files focused (under 50 lines of rule content) +- YAML frontmatter is mandatory + +## Glob Specificity Rules + +| Pattern | Acceptable? | Why | +|---------|:-----------:|-----| +| `src/**/*` | Yes | Targets specific directory | +| `**/*.ts` | Yes | Targets specific file type | +| `src/**/*.tsx` | Yes | Combines directory + type | +| `*` | No | Too broad — would match everything | +| `**/*` | No | Equivalent to matching all files | + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No `.cursor/rules/` directory | Create directory and add rule files starting at 900 | +| Directory exists with rules | Scan for glob collisions, use next available number | +| Glob collision detected | Report conflict, propose narrower glob or skip | + +Never modify or renumber existing `.mdc` files. + +## Collision Detection Protocol + +Before writing ANY .mdc file: +1. Read all existing `.mdc` files in `.cursor/rules/` +2. Extract each file's `globs` value from frontmatter +3. Compare proposed globs against existing globs +4. If overlap exists: report which file conflicts, what its glob is, and why they conflict +5. Propose alternatives: narrower glob, different file scope, or skip + +## Examples + +### Example 1: Simple project context + +```yaml +--- +description: Project context and quality gates for agentic-os +globs: src/**/* +alwaysApply: true +--- +# Project Standards + +This is a TypeScript project using Vitest for testing. + +When working in src/: +- Run `npm test` before considering work complete +- Run `npm run lint` to verify code style +- New files should have corresponding .test.ts files +``` + +### Example 2: Persona routing (Complex tier) + +```yaml +--- +description: Persona routing — Architecture domain +globs: Designs/**/* +alwaysApply: true +--- +# Architect Mode + +When working in Designs/: +- Prioritize structural scalability and system design patterns +- Reference AGENTS.md for full persona guidelines +- Cross-reference existing blueprints before proposing new designs +- Do not apply patterns from Operations/ or Infrastructure/ +``` + +### Example 3: Scope isolation (Complex tier) + +```yaml +--- +description: Scope isolation between concern domains +globs: Operations/**/*,Designs/**/*,Infrastructure/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in Operations/: +- Do not suggest content from Designs/ or Infrastructure/ + +When working in Designs/: +- Do not suggest content from Operations/ or Infrastructure/ + +When working in Infrastructure/: +- Do not suggest content from Operations/ or Designs/ +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Cursor as a runtime. It formats the assembled proposal (from templates) into Cursor-native `.mdc` files, respecting numbering conventions, glob specificity, and collision detection requirements. diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/agents/openai.yaml new file mode 100644 index 0000000..d13d161 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/agents/openai.yaml @@ -0,0 +1,5 @@ +name: agentic-os-setup +description: AI-assisted repo setup — scans structure, classifies complexity, proposes configuration proportional to detected needs. Use when setting up agentic-os on an existing project. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/catalog.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/catalog.md new file mode 100644 index 0000000..613ec51 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/catalog.md @@ -0,0 +1,213 @@ +# Signal Catalog + +## Purpose + +Structured reference of known filesystem patterns and their meanings. The AI uses this catalog to anchor detection during repo scanning. Patterns not listed here do not prevent the AI from reasoning about novel structures — this is a reference, not a hard gate. + +--- + +## Signal: .cursor/rules/ + +**Pattern:** Directory `.cursor/rules/` exists with `.mdc` files +**Indicates:** Existing Cursor AI configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Scan existing rules for glob patterns (collision detection) +- Detect numbering convention (respect existing band) +- Generate agentic-os rule in next available number slot +**Coexistence:** Additive only — never modify existing rules + +--- + +## Signal: CLAUDE.md + +**Pattern:** File `CLAUDE.md` at repo root +**Indicates:** Existing Claude Code configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Do not overwrite — create `CLAUDE-agentic-os.md` as companion file +- Reference companion from proposal +**Coexistence:** Companion file pattern + +--- + +## Signal: .clinerules + +**Pattern:** File `.clinerules` at repo root +**Indicates:** Existing Cline configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Do not overwrite — create `.clinerules-agentic-os` as companion file +**Coexistence:** Companion file pattern + +--- + +## Signal: AGENTS.md + +**Pattern:** File `AGENTS.md` at repo root +**Indicates:** Existing agent instructions (possibly Antigravity or hand-written) +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Extend with managed block (append below existing content) +- Never replace or modify existing content +**Coexistence:** Managed block append pattern + +--- + +## Signal: _bmad/ + +**Pattern:** Directory `_bmad/` at repo root +**Indicates:** BMad agent framework installed +**Complexity impact:** Automatically Complex tier (framework presence) +**Setup implications:** +- Defer persona routing entirely to BMAD +- Only generate: scope isolation, cross-reference, naming enforcement +- Explain deferral in proposal +**Coexistence:** Defer persona ownership + +--- + +## Signal: .claude/ + +**Pattern:** Directory `.claude/` at repo root +**Indicates:** Claude Code project configuration or skills +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Inspect for skills/ subdirectory +- Note existing configuration approach +**Coexistence:** Do not modify contents + +--- + +## Signal: package.json + +**Pattern:** File `package.json` at repo root +**Indicates:** Node.js/JavaScript project +**Complexity impact:** +1 concern folder (if workspaces found: +1 per workspace root) +**Setup implications:** +- Check for `workspaces` field (monorepo indicator → Multi or Complex) +- Detect test framework (jest, vitest, mocha) for quality gate template +- Note scripts for build/test/lint commands +**Coexistence:** Read-only reference + +--- + +## Signal: pyproject.toml + +**Pattern:** File `pyproject.toml` at repo root +**Indicates:** Python project (modern packaging) +**Complexity impact:** +1 concern folder +**Setup implications:** +- Check for monorepo tools (hatch workspaces, pants) +- Detect test framework (pytest, unittest) +- Note linting tools (ruff, black, mypy) +**Coexistence:** Read-only reference + +--- + +## Signal: Cargo.toml + +**Pattern:** File `Cargo.toml` at repo root +**Indicates:** Rust project +**Complexity impact:** +1 concern folder (if workspace: +1 per member) +**Setup implications:** +- Check for `[workspace]` section (monorepo indicator) +- Note crate structure for scope isolation +**Coexistence:** Read-only reference + +--- + +## Signal: go.mod + +**Pattern:** File `go.mod` at repo root +**Indicates:** Go project +**Complexity impact:** +1 concern folder +**Setup implications:** +- Check for go.work (multi-module workspace) +- Note module path for naming conventions +**Coexistence:** Read-only reference + +--- + +## Signal: terraform/ + +**Pattern:** Directory `terraform/` or `infra/` with `.tf` files +**Indicates:** Infrastructure-as-Code component +**Complexity impact:** +1 concern folder +**Setup implications:** +- Distinct concern domain (infrastructure vs application code) +- Consider scope isolation between IaC and app code +- Note state backend for quality gate template +**Coexistence:** Read-only reference + +--- + +## Signal: docker-compose.yml + +**Pattern:** File `docker-compose.yml` or `docker-compose.yaml` at root +**Indicates:** Multi-service local development setup +**Complexity impact:** +1 concern folder (if 3+ services) +**Setup implications:** +- Indicates multiple services that may need scope isolation +- Service names can inform persona routing +**Coexistence:** Read-only reference + +--- + +## Signal: .github/ + +**Pattern:** Directory `.github/` with workflows/ +**Indicates:** GitHub Actions CI/CD pipeline +**Complexity impact:** Neutral (doesn't affect tier directly) +**Setup implications:** +- Note CI structure for quality gate template +- Detect workflow organization patterns +**Coexistence:** Read-only reference + +--- + +## Signal: docs/ + +**Pattern:** Directory `docs/` at root +**Indicates:** Documentation as a distinct concern +**Complexity impact:** +1 concern folder +**Setup implications:** +- Potential scope isolation (docs vs code) +- May indicate architectural documentation needs +**Coexistence:** Read-only reference + +--- + +## Signal: Makefile + +**Pattern:** File `Makefile` at repo root +**Indicates:** Build automation (often multi-concern orchestration) +**Complexity impact:** Neutral (indicator of maturity, not complexity) +**Setup implications:** +- Read target names for project structure hints +- Note common targets (build, test, lint, deploy) +**Coexistence:** Read-only reference + +--- + +## Signal: src/ + +**Pattern:** Directory `src/` at repo root (without other concern folders) +**Indicates:** Single-purpose project with conventional structure +**Complexity impact:** Neutral (alone = Simple tier cap) +**Setup implications:** +- If `src/` is the only concern folder, tier should not exceed Simple +- Common in libraries, CLI tools, single applications +**Coexistence:** Read-only reference + +--- + +## Usage Context + +The AI reads this catalog during the scanning phase to: +1. Identify which signals are present in the target repo +2. Map each signal to its complexity dimension contribution +3. Determine coexistence behavior before proposing any output +4. Anchor decisions in documented patterns rather than hallucination + +Signals not in this catalog can still be reasoned about — this catalog accelerates recognition of common patterns but does not limit the AI's analytical capability. diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/examples/complex-output.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/examples/complex-output.md new file mode 100644 index 0000000..73137f7 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/examples/complex-output.md @@ -0,0 +1,150 @@ +# Calibration Example: Complex Tier Output + +## Scenario + +A multi-concern monorepo with `Designs/`, `Operations/`, `Team-Workitems/`, `Infrastructure/`, and `docs/` at root. Existing `.cursor/rules/` (files 800-805), existing AGENTS.md. Two team indicators. Cross-references between Operations and Designs. + +**Detected signals:** .cursor/rules/ (6 files, 800-band), AGENTS.md, 5 concern folders, team indicators, cross-domain references +**Classification:** Complex (5+ concern folders, 4+ AI configs, 2 teams, 2+ cross-refs) +**Runtimes targeted:** claude, cursor, antigravity + +## Expected Output + +### File: CLAUDE-agentic-os.md (companion — existing CLAUDE.md untouched) + +```markdown +# Agentic-OS Configuration + +## Persona Routing + +- **Architect Mode:** Triggered when editing `/Designs/`. Prioritize structural scalability, system design patterns, and requirements traceability. +- **Operations Mode:** Triggered when editing `/Operations/`. Focus on process efficiency, candidate assessment, and documentation completeness. +- **Engineering Mode:** Triggered when editing `/Infrastructure/`. Focus on reliability, security, and operational readiness. + +See AGENTS.md for full persona definitions. + +## Scope Isolation + +The following domains are isolated — do not cross-reference unless explicitly asked: +- `/Designs/` and `/Operations/` are independent concerns +- `/Infrastructure/` and `/Team-Workitems/` are independent concerns + +## Cross-Reference Rules + +- **Operations/ → Designs/**: Interview files must reference a valid job description via `Job-ID:` frontmatter field +- **Team-Workitems/ → Designs/**: Work items should trace to design documents via `Design-Ref:` field + +## Naming Conventions + +### Operations/job-interviews/ +- Candidate files: `candidate_[first-name]-[last-name].md` + +### Team-Workitems/ +- Work items: `[priority]-[short-description].md` + +## Quality Gates + +Before completing work, verify: +- **Linting**: `make lint` +- **Tests**: `make test` +- **Cross-references**: Verify linked documents exist +``` + +### File: .cursor/rules/806-agentic-os-personas.mdc + +```yaml +--- +description: Persona routing for agentic-os domains — Designs +globs: Designs/**/* +alwaysApply: true +--- +# Architect Mode + +When working in Designs/: +- Prioritize structural scalability and system design metrics +- Reference AGENTS.md for architecture persona guidelines +- Cross-reference parent blueprints for requirements traceability +- Do not suggest patterns from Operations/ or Infrastructure/ +``` + +### File: .cursor/rules/807-agentic-os-isolation.mdc + +```yaml +--- +description: Scope isolation between concern domains +globs: Operations/**/*,Designs/**/*,Team-Workitems/**/*,Infrastructure/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in Operations/: +- Do not read or suggest content from Designs/ or Infrastructure/ +- Keep completions scoped to HR/recruitment conventions + +When working in Designs/: +- Do not read or suggest content from Operations/ or Team-Workitems/ +- Keep completions scoped to architecture patterns + +When working in Infrastructure/: +- Do not read or suggest content from Operations/ or Designs/ +- Keep completions scoped to IaC and deployment patterns +``` + +### File: AGENTS.md (extended via managed block — existing content preserved above) + +```markdown + +## Agentic-OS Generated Rules + +### Personas + +#### Architect +**Scope:** `/Designs/` +**Focus:** System design, scalability, requirements traceability +**Behavioral rules:** +- Prioritize structural patterns over quick fixes +- Reference existing blueprints before proposing new structures +- Validate against design principles in docs/ + +#### Operations Specialist +**Scope:** `/Operations/` +**Focus:** Process efficiency, documentation completeness, candidate assessment +**Behavioral rules:** +- Follow HR documentation standards +- Enforce cross-reference rules (interviews → job descriptions) +- Maintain naming conventions strictly + +#### Infrastructure Engineer +**Scope:** `/Infrastructure/` +**Focus:** Reliability, security, operational readiness +**Behavioral rules:** +- Validate against security baselines +- Consider blast radius of changes +- Reference runbooks for operational procedures + +### Scope Boundaries + +| Domain | Isolated From | Rationale | +|--------|--------------|-----------| +| Designs/ | Operations/, Team-Workitems/ | Architecture concerns are independent of HR operations | +| Operations/ | Designs/, Infrastructure/ | Recruitment is independent of system design | +| Infrastructure/ | Operations/, Designs/ | IaC has distinct safety requirements | + +### Cross-References + +| Source | Target | Link Format | Rule | +|--------|--------|-------------|------| +| Operations/job-interviews/ | Operations/job-descriptions/ | `Job-ID: jd-*` | Every interview file must link to a valid JD | +| Team-Workitems/ | Designs/ | `Design-Ref: *` | Work items should trace to design docs | + + +``` + +## Volume Calibration + +Complex tier output should be: +- Multiple config files per runtime (personas, isolation, cross-refs may be separate) +- AGENTS.md with full persona definitions and relationship tables +- 50-150 lines per major file +- Comprehensive organizational rules covering personas, isolation, cross-references, and naming +- Cursor rules in separate files by concern (personas, isolation) to avoid glob conflicts diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/examples/simple-output.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/examples/simple-output.md new file mode 100644 index 0000000..72a5545 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/examples/simple-output.md @@ -0,0 +1,65 @@ +# Calibration Example: Simple Tier Output + +## Scenario + +A single-purpose Node.js project with `src/`, `tests/`, `package.json`, and a `.github/workflows/` directory. No existing AI config. One developer. + +**Detected signals:** package.json (jest, eslint), src/, .github/ +**Classification:** Simple (1 concern folder, 0 AI configs, 0 teams, 0 cross-refs, no framework) +**Runtimes targeted:** claude, cursor + +## Expected Output + +### File: CLAUDE.md + +```markdown +# Project Context + +This is a Node.js project using Jest for testing and ESLint for linting. + +## Quality Gates + +Before completing work: +- Run tests: `npm test` +- Run linting: `npm run lint` +- Ensure new code has corresponding test coverage + +## Project Structure + +- `src/` — Application source code +- `tests/` — Test files (Jest) +- `.github/workflows/` — CI pipeline +``` + +### File: .cursor/rules/900-agentic-os.mdc + +```yaml +--- +description: Project context and quality gates for agentic-os +globs: src/**/* +alwaysApply: true +--- +# Project Standards + +This is a Node.js project. When working in src/: +- Run `npm test` before considering work complete +- Run `npm run lint` to verify code style +- New source files should have corresponding test files in tests/ +- Follow existing naming conventions in src/ +``` + +## What is NOT Generated (Simple Tier) + +- No AGENTS.md (not enough complexity for personas) +- No GOALS.md (not a multi-concern workspace) +- No persona routing (single domain) +- No scope isolation (single domain) +- No cross-reference enforcement (no relationships detected) + +## Volume Calibration + +Simple tier output should be: +- 1 file per targeted runtime +- Under 30 lines per file +- Focused on project context and quality gates only +- No organizational/behavioral rules diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/cross-reference.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/cross-reference.md new file mode 100644 index 0000000..e61e739 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/cross-reference.md @@ -0,0 +1,61 @@ +# Template: Cross-Reference Enforcement + +## Intent + +Enforce that files in one domain correctly reference files in another domain where a declared relationship exists. Catches broken links, missing references, and orphaned documents. + +## Inputs Required + +- `{relationships}`: List of source → target relationships with their linking mechanism +- `{source_domain}`: Domain where the referencing file lives +- `{target_domain}`: Domain where the referenced file lives +- `{link_format}`: How the reference is expressed (frontmatter field, inline link, filename convention) + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Cross-reference enforcement — {source_domain} → {target_domain} +globs: {source_domain}/**/* +alwaysApply: true +--- +# Cross-Reference Rules + +Every file in `{source_domain}/` that matches `{file_pattern}` MUST: +- {reference_requirement_1} +- {reference_requirement_2} + +Validation: +- Check that referenced {target_domain} file exists +- Warn if reference format doesn't match: `{link_format}` +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Cross-Reference Rules + +{for each relationship} +- **{source_domain}/ → {target_domain}/**: Files matching `{file_pattern}` must contain a reference to a valid `{target_domain}` file using format: `{link_format}` +{end for} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Relationship Enforcement + +{for each relationship} +### {relationship_name} +**Source:** `/{source_domain}/{file_pattern}` +**Target:** `/{target_domain}/` +**Link format:** `{link_format}` +**Rule:** {enforcement_description} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** Cross-domain references found (e.g., interview files referencing job descriptions, work items referencing design docs, tests referencing source modules) +- **Requires:** User confirmation for AI-inferred relationships (only manifest-declared relationships are auto-included) diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/naming-enforcement.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/naming-enforcement.md new file mode 100644 index 0000000..b0b0890 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/naming-enforcement.md @@ -0,0 +1,67 @@ +# Template: Naming Enforcement + +## Intent + +Enforce consistent file and directory naming conventions within a domain. Catches deviations from established patterns and guides creation of new files. + +## Inputs Required + +- `{domain}`: Domain path where naming rules apply +- `{patterns}`: List of naming patterns with their regex or description +- `{examples}`: Valid and invalid filename examples + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Naming conventions for {domain} +globs: {domain}/**/* +alwaysApply: true +--- +# Naming Conventions + +Files in `{domain}/` follow these patterns: + +{for each pattern} +- **{file_type}**: `{naming_pattern}` + Example: `{valid_example}` +{end for} + +When creating new files in this domain: +- Follow the naming pattern exactly +- Warn if a proposed filename doesn't match the convention +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Naming Conventions + +{for each domain_with_patterns} +### {domain}/ +{for each pattern} +- `{file_type}` files: `{naming_pattern}` (e.g., `{valid_example}`) +{end for} +{end for} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Naming Standards + +{for each domain_with_patterns} +### {domain} +| File Type | Pattern | Example | +|-----------|---------|---------| +{for each pattern} +| {file_type} | `{naming_pattern}` | `{valid_example}` | +{end for} +{end for} +``` + +## When to Use + +- **Complexity tier:** Simple, Multi, or Complex (applicable at any tier where patterns are detected) +- **Detected signals:** Consistent naming patterns observed in existing files (3+ files following same convention) +- **Common patterns:** kebab-case files, prefixed files (NNN-name.ext), date-prefixed (YYYY-MM-DD-name), type-prefixed (feat-*, fix-*) diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/persona-routing.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/persona-routing.md new file mode 100644 index 0000000..9c69303 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/persona-routing.md @@ -0,0 +1,66 @@ +# Template: Persona Routing + +## Intent + +Route AI persona/behavior based on which folder the user is editing in. Each concern domain gets a distinct behavioral mode optimized for that domain's work. + +## Inputs Required + +- `{domains}`: List of detected concern domains with their folder paths +- `{personas}`: Mapping of domain → persona name and behavioral description +- `{repo_name}`: Repository name for context + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Persona routing for agentic-os domains — {domain_name} +globs: {domain_path}/**/* +alwaysApply: true +--- +# {persona_name} Mode + +When working in `{domain_path}/`: +- {persona_behavioral_rule_1} +- {persona_behavioral_rule_2} +- {persona_behavioral_rule_3} + +Reference AGENTS.md for full persona guidelines. +``` + +One .mdc file per domain. Each gets a specific glob. + +## Output Pattern (CLAUDE.md section) + +```markdown +## Persona Routing + +{for each domain} +- **{persona_name} Mode:** Triggered when editing `/{domain_path}/`. {persona_behavioral_summary} +{end for} + +See AGENTS.md for full persona definitions. +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Personas + +{for each domain} +### {persona_name} + +**Scope:** `/{domain_path}/` +**Focus:** {persona_focus_description} +**Behavioral rules:** +- {rule_1} +- {rule_2} +- {rule_3} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** 2+ distinct concern domains with different intent (e.g., `Designs/` + `Operations/` or `frontend/` + `backend/` + `infra/`) +- **NOT when:** Single-purpose repo, or `_bmad/` detected (defer persona ownership to BMAD) diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/quality-gates.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/quality-gates.md new file mode 100644 index 0000000..35d64c3 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/quality-gates.md @@ -0,0 +1,72 @@ +# Template: Quality Gates + +## Intent + +Define quality checks that the AI should enforce or remind about when creating or modifying files within a domain. Derived from detected tooling (linters, test frameworks, CI pipelines). + +## Inputs Required + +- `{domain}`: Domain path or glob where quality gates apply +- `{gates}`: List of quality checks with their commands or descriptions +- `{test_framework}`: Detected test framework (jest, pytest, cargo test, go test, etc.) +- `{lint_tools}`: Detected linting/formatting tools +- `{ci_checks}`: Known CI pipeline checks + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Quality gates for {domain} +globs: {domain}/**/*.{extensions} +alwaysApply: true +--- +# Quality Gates + +Before considering work in `{domain}/` complete: + +{for each gate} +- [ ] {gate_description}: `{gate_command}` +{end for} + +When creating new files: +- Ensure they have corresponding test files (if test framework detected) +- Follow existing patterns for test file location and naming +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Quality Gates + +Before completing work, verify: + +{for each gate} +- **{gate_name}**: `{gate_command}` — {gate_purpose} +{end for} + +Test framework: {test_framework} +Test location: {test_directory_pattern} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Quality Standards + +### Pre-Completion Checklist +{for each gate} +- [ ] **{gate_name}**: {gate_description} + Command: `{gate_command}` +{end for} + +### Testing Requirements +- Framework: {test_framework} +- Location: `{test_directory_pattern}` +- Coverage: {coverage_expectations} +``` + +## When to Use + +- **Complexity tier:** Simple, Multi, or Complex +- **Detected signals:** Test framework present (package.json scripts, pytest.ini, Cargo.toml test config), linting tools configured (.eslintrc, ruff.toml, .golangci.yml), CI workflows present (.github/workflows/) +- **Scales with tier:** Simple = test + lint only; Multi/Complex = full gate set including build verification diff --git a/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/scope-isolation.md b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/scope-isolation.md new file mode 100644 index 0000000..d3ba8e3 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/agentic-os-setup/templates/scope-isolation.md @@ -0,0 +1,64 @@ +# Template: Scope Isolation + +## Intent + +Prevent AI from cross-contaminating context between unrelated concern domains. When working in one domain, the AI should not suggest content from or reference patterns in other domains unless explicitly asked. + +## Inputs Required + +- `{domains}`: List of domain paths that should be isolated from each other +- `{isolation_pairs}`: Specific pairs of domains that must not cross-reference + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Scope isolation between concern domains +globs: {domain_path_1}/**/*,{domain_path_2}/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in `{domain_path_1}/`: +- Do not read or suggest content from {other_domains} +- Do not apply patterns from {other_domains} to this domain +- Keep completions scoped to this domain's conventions + +When working in `{domain_path_2}/`: +- Do not read or suggest content from {other_domains} +- Do not apply patterns from {other_domains} to this domain +- Keep completions scoped to this domain's conventions +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Scope Isolation + +The following domains are isolated — do not cross-reference unless explicitly asked: + +{for each isolation_pair} +- `/{domain_a}/` and `/{domain_b}/` are independent concerns +{end for} + +When editing in one domain, restrict suggestions and completions to that domain's patterns and conventions. +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Scope Boundaries + +{for each domain} +### {domain_name} +**Path:** `/{domain_path}/` +**Isolated from:** {list_of_other_domains} +**Rationale:** {why_these_are_separate_concerns} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** 2+ concern domains that serve different purposes (e.g., infrastructure vs application code, documentation vs implementation) +- **Always pair with:** Persona Routing (if personas are generated, isolation prevents persona bleed) diff --git a/examples/uj-1-node-monorepo/.agents/skills/assumption-mapping/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/assumption-mapping/SKILL.md new file mode 100644 index 0000000..89e444a --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/assumption-mapping/SKILL.md @@ -0,0 +1,65 @@ +--- +name: assumption-mapping +description: Surface and categorize assumptions underlying product strategy. Use early in development to document what you're betting on. +--- + +# Assumption Mapping + +Generate and categorize assumptions underlying a product strategy. + +## When to Use + +Early in product development to surface and document what you're betting on. + +## The Framework + +Organize assumptions into four categories: + +| Category | Focus | Example Questions | +|----------|-------|-------------------| +| **Desirability** | Will users want this? | Problem severity, willingness to pay, switching triggers | +| **Feasibility** | Can we build it? | Technical risks, data needs, integrations, security | +| **Viability** | Will it make money? | Pricing, margins, retention, unit economics | +| **Usability** | Can users use it? | Task success, learnability, error tolerance | + +## The Process + +### 1. Gather Inputs + +Document: +- Product description +- Core problem being solved +- Target user + +### 2. Generate Assumptions + +For each category, create at least 5 assumptions: + +**Format:** +- Statement: "We believe that [specific, falsifiable claim]" +- Impact if wrong: [concrete consequence] + +**Good example:** +- Statement: "We believe that SMB admins will pay $20/user/month if onboarding drops below 30 minutes" +- Impact if wrong: Premium pricing underperforms due to insufficient WTP + +### 3. Quality Check + +Each assumption should be: +- Specific (include numbers, segments, timeframes) +- Testable (you could run an experiment) +- One idea per assumption (no compound claims) + +## Output + +Four lists of 5+ assumptions each: +- Desirability assumptions +- Feasibility assumptions +- Viability assumptions +- Usability assumptions + +Each with statement and impact if wrong. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/assumption-mapping/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/assumption-mapping/agents/openai.yaml new file mode 100644 index 0000000..d606257 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/assumption-mapping/agents/openai.yaml @@ -0,0 +1,5 @@ +name: assumption-mapping +description: Surface and categorize assumptions underlying product strategy. Use early in development to document what you're betting on. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/assumption-prioritization/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/assumption-prioritization/SKILL.md new file mode 100644 index 0000000..ecfa95b --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/assumption-prioritization/SKILL.md @@ -0,0 +1,66 @@ +--- +name: assumption-prioritization +description: Prioritize assumptions by risk and importance. Use after assumption mapping to decide what to test first. +--- + +# Assumption Prioritization + +Prioritize assumptions to focus validation efforts on what matters most. + +## When to Use + +After assumption mapping, to decide which assumptions to test first. + +## The Framework + +Score each assumption on two dimensions: + +**Importance (1-5):** Business impact if false +- 5 = Strategy fails, >20% revenue hit +- 4 = Major adoption/cost driver (10-20%) +- 3 = Moderate impact (5-10%) +- 2 = Minor impact (<5%) +- 1 = Negligible + +**Certainty (1-5):** Evidence that it's true +- 1 = No evidence, conjecture +- 2 = Anecdotes, untested +- 3 = Early signals, small samples +- 4 = Strong directional data +- 5 = Robust evidence, production proof + +**Risk Score = Importance x (6 - Certainty)** + +Higher score = riskier assumption = test first + +## The Process + +### 1. Score Each Assumption + +Consider: +- Impact severity from "impact if wrong" +- Blast radius (users/systems affected) +- Irreversibility (cost to fix later) +- Dependencies (does it block others?) +- Evidence quality + +### 2. Map to Quadrants + +| | Low Certainty | High Certainty | +|---|---|---| +| **High Importance** | TEST FIRST | Monitor | +| **Low Importance** | Deprioritize | Ignore | + +### 3. Rank by Risk Score + +Focus validation on High Importance / Low Certainty assumptions. + +## Output + +- 2x2 summary with counts per quadrant +- Top risks ranked by score with rationale +- Full ranked list of all assumptions + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/assumption-prioritization/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/assumption-prioritization/agents/openai.yaml new file mode 100644 index 0000000..f31a352 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/assumption-prioritization/agents/openai.yaml @@ -0,0 +1,5 @@ +name: assumption-prioritization +description: Prioritize assumptions by risk and importance. Use after assumption mapping to decide what to test first. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/atlassian-jira-sync/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/atlassian-jira-sync/SKILL.md new file mode 100644 index 0000000..71a7ff0 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/atlassian-jira-sync/SKILL.md @@ -0,0 +1,98 @@ +--- +name: atlassian-jira-sync +description: Sync Jira issues with local tasks. Use during daily planning or when user asks about Jira issues. +--- + +# Jira Issue Sync + +Check Jira for assigned issues and sync with local task management. + +## Instructions + +### Step 1: Fetch Assigned Issues + +Call `jira_search` with JQL: +``` +assignee = currentUser() AND status != Done ORDER BY priority DESC +``` + +### Step 2: Compare with Local Tasks + +Check `Tasks/` for existing files with Jira references: +- Look for `jira_key` in YAML frontmatter +- Identify new issues not yet in Tasks/ + +### Step 3: Present Summary + +``` +Jira Issues (8 active): + +**Blockers/Critical** +- PROJ-123: Production bug in auth [In Progress] + +**High Priority** +- PROJ-124: API rate limiting [To Do] +- PROJ-125: Update deployment docs [In Review] + +**Normal** +- PROJ-126: Refactor logging [Backlog] + +3 issues not yet in local Tasks. Create them? +``` + +### Step 4: Sync Options + +| Option | Description | +|--------|-------------| +| Create all | Add all new issues as local tasks | +| Select specific | Choose which to sync | +| Skip | Continue without syncing | + +### Step 5: Create Local Tasks + +For each issue to sync, create task file: + +```yaml +--- +title: [Issue summary] +category: technical +priority: [Map from Jira priority] +status: n +jira_key: PROJ-XXX +--- +``` + +## Priority Mapping + +| Jira | Personal OS | +|------|-------------| +| Blocker | P0 | +| Critical | P0 | +| High | P1 | +| Medium | P2 | +| Low | P3 | + +## Example Flow + +**User:** "What should I work on today?" + +**Agent:** +1. Fetches Jira issues +2. Compares with local tasks +3. "You have 5 Jira tickets..." +4. Offers to create local tasks +5. Continues with planning + +## Notes + +- Keep `jira_key` in frontmatter for bidirectional sync +- Update Jira status when local task completes +- Include Jira link in task context section + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/atlassian-jira-sync/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/atlassian-jira-sync/agents/openai.yaml new file mode 100644 index 0000000..8482a2b --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/atlassian-jira-sync/agents/openai.yaml @@ -0,0 +1,5 @@ +name: atlassian-jira-sync +description: Sync Jira issues with local tasks. Use during daily planning or when user asks about Jira issues. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/backend-design/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/backend-design/SKILL.md new file mode 100644 index 0000000..aa3964f --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/backend-design/SKILL.md @@ -0,0 +1,96 @@ +--- +name: backend-design +description: Design backend architecture for implementation with API contracts, data model changes, service boundaries, security, and observability. +--- + +# Backend Design + +Use this skill to design robust backend changes before implementation. + +## The Process + +### Step 1: Define backend objective + +Clarify: +- business objective +- service boundary +- latency/reliability expectations + +### Step 2: Define API and contract changes + +Specify: +- endpoints/events +- request/response schemas +- error model and status mapping + +### Step 3: Define data model and migrations + +Document: +- schema changes +- migration strategy +- backward-compatibility approach + +### Step 4: Define security and observability + +Include: +- authn/authz requirements +- rate limiting/abuse controls +- logging, metrics, tracing +- alerting conditions + +### Step 5: Define rollout and verification + +Provide: +- phased rollout or feature flags +- rollback strategy +- verification checks and commands + +## Output Format + +```markdown +# [Feature Name] Backend Design Spec + +## Objective +- Goal: +- Service boundary: + +## API Contracts +- Endpoint/event definitions: +- Request/response schema: +- Error model: + +## Data Model +- Schema changes: +- Migration plan: +- Compatibility notes: + +## Security and Reliability +- Authn/authz: +- Abuse controls: +- Reliability constraints: + +## Observability +- Logs: +- Metrics: +- Traces: +- Alerts: + +## Rollout and Verification +- Rollout plan: +- Rollback plan: +- Verification commands/evidence: +``` + +## Quality Bar + +- Contracts must be explicit and testable +- Migration and rollback must be present for schema changes +- Verification must include observable evidence + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/backend-design/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/backend-design/agents/openai.yaml new file mode 100644 index 0000000..e7d3151 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/backend-design/agents/openai.yaml @@ -0,0 +1,5 @@ +name: backend-design +description: Design backend architecture for implementation with API contracts, data model changes, service boundaries, security, and observability. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/brainstorming/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/brainstorming/SKILL.md new file mode 100644 index 0000000..829b1bf --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/brainstorming/SKILL.md @@ -0,0 +1,60 @@ +--- +name: brainstorming +description: Turn ideas into designs through collaborative dialogue. Use before any creative work - features, components, or modifications. +--- + +# Brainstorming Ideas Into Designs + +Use this before any creative work - creating features, building components, adding functionality, or modifying behavior. + +## Overview + +Turn ideas into fully formed designs through collaborative dialogue. Understand before implementing. + +## The Process + +**Understanding the idea:** +- Check out current project state first (files, docs, recent changes) +- Ask questions one at a time to refine the idea +- Prefer multiple choice questions when possible +- Only one question per message - break complex topics into multiple questions +- Focus on: purpose, constraints, success criteria + +**Exploring approaches:** +- Propose 2-3 different approaches with trade-offs +- Lead with your recommended option and explain why +- Present options conversationally + +**Presenting the design:** +- Once you understand what you're building, present the design +- Break into sections of 200-300 words +- Ask after each section whether it looks right +- Cover: architecture, components, data flow, error handling, testing +- Be ready to go back and clarify if something doesn't make sense + +## After the Design + +**Documentation:** +- Write the validated design to a planning document +- Commit the design before starting implementation + +**Implementation:** +- Ask: "Ready to set up for implementation?" +- Use `writing-plans.md` skill to create detailed implementation plan + +## Key Principles + +- **One question at a time** - Don't overwhelm with multiple questions +- **Multiple choice preferred** - Easier to answer when possible +- **YAGNI ruthlessly** - Remove unnecessary features from designs +- **Explore alternatives** - Always propose 2-3 approaches before settling +- **Incremental validation** - Present design in sections, validate each +- **Be flexible** - Go back and clarify when something doesn't make sense + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/brainstorming/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/brainstorming/agents/openai.yaml new file mode 100644 index 0000000..07f3118 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/brainstorming/agents/openai.yaml @@ -0,0 +1,5 @@ +name: brainstorming +description: Turn ideas into designs through collaborative dialogue. Use before any creative work - features, components, or modifications. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/challenging-stakeholder-questions/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/challenging-stakeholder-questions/SKILL.md new file mode 100644 index 0000000..c23f876 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/challenging-stakeholder-questions/SKILL.md @@ -0,0 +1,34 @@ +--- +name: challenging-stakeholder-questions +description: Generate rigorous stakeholder challenge questions for proposal or meeting preparation. +--- + +# Challenging Stakeholder Questions + +Generate probing questions that pressure-test a proposal. + +## Instructions + +### Step 1: Parse context +- Use goal/context and stakeholder details. +- State assumptions if details are missing. + +### Step 2: Generate question set +- Produce at least 20 non-redundant questions. +- Cover: financials, resources, timeline, risks, market, competition, feasibility, UX, ethics, sustainability, team capability, performance history, strategic alignment, compliance, scalability. + +### Step 3: Check quality +- Remove generic and repetitive questions. +- Ensure each question ties to provided context. + +## Output + +- Numbered question list (20+) + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/challenging-stakeholder-questions/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/challenging-stakeholder-questions/agents/openai.yaml new file mode 100644 index 0000000..82a5b82 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/challenging-stakeholder-questions/agents/openai.yaml @@ -0,0 +1,5 @@ +name: challenging-stakeholder-questions +description: Generate rigorous stakeholder challenge questions for proposal or meeting preparation. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/competitor-analysis/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/competitor-analysis/SKILL.md new file mode 100644 index 0000000..be63598 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/competitor-analysis/SKILL.md @@ -0,0 +1,76 @@ +--- +name: competitor-analysis +description: Analyze competitors using Porter's four-component model - drivers, assumptions, strategy, capabilities. +--- + +# Competitor Analysis (Porter) + +Analyze competitors using Porter's four-component model. + +## When to Use + +When you need to understand a competitor's strategy, capabilities, and likely moves. + +## The Framework + +Porter's four components: + +| Component | Questions | +|-----------|-----------| +| **Objectives** | What are they trying to achieve? (growth, profit, share, positioning) | +| **Current Strategy** | How are they competing? (segments, pricing, channels, roadmap) | +| **Assumptions** | What do they believe about the market, themselves, and rivals? | +| **Capabilities** | What can they actually do? (resources, competencies, gaps) | + +## The Process + +### 1. Objectives (Future Goals) +- Economic goals (growth, profitability, market share) +- Strategic goals (positioning, tech leadership, ecosystem) +- Timeframes and indicators +- Priority ranking + +### 2. Current Strategy +- Target segments and value proposition +- Pricing and monetization +- Go-to-market (channels, partnerships) +- Product roadmap themes +- Geographic posture + +### 3. Assumptions +- About the industry (demand, regulation, tech trajectory) +- About themselves (core competencies, cost position) +- About you and other rivals +- Implicit beliefs inferred from behavior + +### 4. Capabilities +- Tangible: cost structure, capacity, balance sheet +- Intangible: brand, IP, data, culture, talent +- Activities across value chain +- Notable gaps and constraints + +### 5. Synthesize: Likely Moves + +Based on the four components: +- What will they respond to quickly vs. ignore? +- Probable near-term moves (ranked by likelihood) +- Expected response speed by move type + +### 6. Implications for Us +- Risks to monitor +- Opportunities to exploit +- Recommended counter-moves +- "If they do X, we do Y" mapping + +## Output + +- Executive snapshot +- Four components analysis +- Likely moves and response profile +- Implications and recommendations +- Evidence sources +- Unknowns and validation plan + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/competitor-analysis/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/competitor-analysis/agents/openai.yaml new file mode 100644 index 0000000..7d1ad0d --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/competitor-analysis/agents/openai.yaml @@ -0,0 +1,5 @@ +name: competitor-analysis +description: Analyze competitors using Porter's four-component model - drivers, assumptions, strategy, capabilities. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/crux-diagnosis/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/crux-diagnosis/SKILL.md new file mode 100644 index 0000000..c5b5135 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/crux-diagnosis/SKILL.md @@ -0,0 +1,71 @@ +--- +name: crux-diagnosis +description: Identify the pivotal obstacle between current state and desired future. Use when developing strategy. +--- + +# Strategic Crux Diagnosis + +Identify the pivotal obstacle between current state and desired future. + +## When to Use + +When developing strategy or facing complex strategic decisions. + +## The Concept + +**Crux:** The smallest set of obstacles that, if solved, makes everything else tractable or unnecessary. + +## Required Inputs + +Gather before analysis: +- Current state (baseline metrics, capabilities) +- Desired future (time-bound outcome, targets) +- Constraints (budget, headcount, tech, compliance) +- Available assets (data, channels, IP, partnerships) +- Key risks and non-negotiables + +## The Process + +### 1. Map Current to Future + +Create a causal graph: +- Start: Current state +- End: Desired future +- List all blockers in between + +### 2. Score Each Blocker + +Evaluate on: +- **Causal centrality:** How much else depends on this? +- **Bottleneck severity:** How much does it slow everything? +- **Solvability:** Can we actually fix it? +- **Leverage potential:** If solved, how much unlocks? +- **Time to impact:** How fast could we see results? +- **Evidence strength:** How sure are we this is the problem? + +### 3. Identify the Crux + +Find the blocker(s) where: +- Solving it unlocks the most downstream progress +- It's actually solvable given constraints +- Time to impact is acceptable + +### 4. Generate Strategic Options + +Create 4-7 options aimed at the crux: +- Include at least one non-obvious approach +- Include at least one constraint-relaxation option +- Evaluate against decision criteria + +## Output + +- Executive summary (situation, crux, approach) +- Evidence pack (facts, assumptions, uncertainties) +- Crux definition with scoring +- Options comparison table +- Chosen strategy with rationale +- Strategic moves (3-5) with owners and timelines + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/crux-diagnosis/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/crux-diagnosis/agents/openai.yaml new file mode 100644 index 0000000..bd574ed --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/crux-diagnosis/agents/openai.yaml @@ -0,0 +1,5 @@ +name: crux-diagnosis +description: Identify the pivotal obstacle between current state and desired future. Use when developing strategy. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/davci/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/davci/SKILL.md new file mode 100644 index 0000000..e6bab28 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/davci/SKILL.md @@ -0,0 +1,83 @@ +--- +name: davci +description: Define clear decision rights - Decider, Approver, Veto, Consulted, Informed. Use when clarifying who decides. +--- + +# DAVCI Decision Rights + +Define clear decision rights using the DAVCI framework. + +## When to Use + +When you need to clarify who decides, approves, and must be consulted on a decision. + +## The Framework + +| Role | Definition | Rules | +|------|------------|-------| +| **D - Decider** | Single person accountable for outcome | Exactly one per decision | +| **A - Approver** | Can override the Decider | Optional; cannot be the D | +| **V - Veto** | Can block for specific domain | One per domain; time-boxed | +| **C - Consulted** | Has input before decision | Keep to 5 or fewer | +| **I - Informed** | Needs to know after decision | Keep targeted | + +## The Process + +### 1. Define the Decision Object + +Be specific about what's being decided: +- Clear title +- Concrete deadline +- Decision type (Strategy, Scope, Design, Technical, Process, Risk, Commercial) + +### 2. Assign Roles + +**Decider (D):** +- Who is accountable for the outcome? +- Must be one person only + +**Approver (A):** +- Does D need air cover for risk/budget/politics? +- If yes, name person one level up + +**Veto (V):** +- Which domains apply? (Security, Legal, Privacy, Brand, Compliance) +- One person per domain +- Set veto window (default: 48 hours) + +**Consulted (C):** +- Who has unique information to improve the decision? +- Cap at 5; merge by role if needed + +**Informed (I):** +- Who must act after or needs awareness? +- Keep targeted to those who need it + +### 3. Add Decision Metadata + +- **Deadline:** Date and time +- **Escalation:** If blocked 24h, escalate to whom? +- **Success test:** One checkable sentence +- **Comms plan:** Channel, audience, timing + +## Output Format + +``` +Decision: [title] +Deadline: [date/time] +Type: [Strategy/Scope/Design/Technical/Process/Risk/Commercial] + +D: [name, role] +A: [name, role] or None +V: [Domain - name, window hours] +C: [role/name]; [role/name] +I: [role/name]; [role/name] + +Escalation: [name, role] +Success test: [single checkable sentence] +Comms: [channel + audience + timing] +``` + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/davci/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/davci/agents/openai.yaml new file mode 100644 index 0000000..a32c318 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/davci/agents/openai.yaml @@ -0,0 +1,5 @@ +name: davci +description: Define clear decision rights - Decider, Approver, Veto, Consulted, Informed. Use when clarifying who decides. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/decision-journal/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/decision-journal/SKILL.md new file mode 100644 index 0000000..7374968 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/decision-journal/SKILL.md @@ -0,0 +1,63 @@ +--- +name: decision-journal +description: Create structured records of decisions with expected outcomes, probabilities, and quit conditions. Use for important decisions. +--- + +# Decision Journal + +Create structured records of decisions for learning and accountability. + +## When to Use + +When making important decisions that you want to track and learn from. + +## The Framework + +Record these components for each decision: + +### 1. Expected Outcomes +List 3-5 possible outcomes: +- Best case scenario +- Most likely scenario +- Worst case scenario +- Consider short and long-term + +### 2. Probability Estimates +For each outcome, estimate likelihood (must sum to 100%): +- Outcome A: X% +- Outcome B: Y% +- etc. + +### 3. Key Assumptions +List 3-5 critical assumptions: +- What beliefs underlie this decision? +- Which, if wrong, would change the outcome? + +### 4. Base Rates +Research relevant statistics: +- What's typical for this type of decision? +- Historical data or industry averages? +- What do similar situations suggest? + +### 5. Quit Conditions +Define 2-3 triggers to abandon or change course: +- Clear, measurable indicators +- Specific thresholds +- Timeline checkpoints + +### 6. Actual Results +Leave blank initially, fill in later: +- What actually happened? +- Which outcome occurred? +- Were assumptions valid? + +## Review Process + +After outcomes are known: +1. Compare predictions to reality +2. Identify where thinking was wrong +3. Extract lessons for future decisions + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/decision-journal/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/decision-journal/agents/openai.yaml new file mode 100644 index 0000000..0dd13af --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/decision-journal/agents/openai.yaml @@ -0,0 +1,5 @@ +name: decision-journal +description: Create structured records of decisions with expected outcomes, probabilities, and quit conditions. Use for important decisions. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/decision-reversibility/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/decision-reversibility/SKILL.md new file mode 100644 index 0000000..c429014 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/decision-reversibility/SKILL.md @@ -0,0 +1,58 @@ +--- +name: decision-reversibility +description: Classify decisions as Hat/Haircut/Tattoo by reversibility. Use to calibrate how much analysis a decision deserves. +--- + +# Decision Reversibility Classification + +Classify decisions by reversibility to calibrate how much analysis they deserve. + +## When to Use + +Before making a decision, to determine how much deliberation is warranted. + +## The Framework + +Classify decisions into three categories: + +| Type | Reversibility | Analysis Needed | +|------|---------------|-----------------| +| **Hat** | Easily reversible, minimal consequences | Decide quickly | +| **Haircut** | Reversible with effort/time | Moderate analysis | +| **Tattoo** | Largely irreversible, lasting impact | Deep analysis | + +## Analysis Criteria + +Consider these factors: + +1. **Immediate consequences** - What happens right away? +2. **Long-term effects** - On you, team, users, company? +3. **Reversal effort** - Time, money, resources to undo? +4. **Permanent changes** - What can't be undone? + +## Classification Guide + +**Hat (decide fast):** +- Can undo with minimal cost +- No lasting consequences +- Examples: Meeting time, doc format, tool choice + +**Haircut (moderate deliberation):** +- Reversible but requires time/effort +- Temporary discomfort if wrong +- Examples: Feature scope, team process, pricing test + +**Tattoo (deliberate carefully):** +- Largely permanent or very costly to reverse +- Long-lasting consequences +- Examples: Architecture choices, team structure, market positioning + +## Output + +- Decision classification (Hat/Haircut/Tattoo) +- Key factors driving the classification +- Recommended level of analysis + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/decision-reversibility/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/decision-reversibility/agents/openai.yaml new file mode 100644 index 0000000..c91e962 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/decision-reversibility/agents/openai.yaml @@ -0,0 +1,5 @@ +name: decision-reversibility +description: Classify decisions as Hat/Haircut/Tattoo by reversibility. Use to calibrate how much analysis a decision deserves. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/difficult-conversations/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/difficult-conversations/SKILL.md new file mode 100644 index 0000000..c4a24e0 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/difficult-conversations/SKILL.md @@ -0,0 +1,81 @@ +--- +name: difficult-conversations +description: Prepare for challenging conversations using Prepare-Listen-Empathize-Clarify-Solve framework. +--- + +# Difficult Conversation Prep + +Prepare for challenging work conversations using a structured framework. + +## When to Use + +Before any conversation you're dreading or that has conflict potential. + +## The Framework: Prepare-Listen-Empathize-Clarify-Solve + +### 1. Preparation Notes + +Document: +- Your intent (what you want to achieve) +- Non-negotiables (what you won't compromise on) +- Specific facts/examples (concrete, not accusations) +- Language traps to avoid +- Desired outcome +- Success criteria +- Medium choice (in-person/video/async) + +### 2. Opening Lines (3-5 options) + +Create openers that are: +- Neutral, non-accusatory +- Reference concrete impact +- Invite their perspective + +**Examples:** +- "I wanted to talk about [situation] because I've noticed [impact]..." +- "I'd like to understand your perspective on [issue]..." +- "Can we discuss [topic]? I want to make sure we're aligned..." + +### 3. Questions to Ask (5-7) + +Use open questions (what/how/when): +- Avoid "why" framing (feels accusatory) +- Include one perspective-taking question +- Include one constraints question + +### 4. Anticipate Reactions + +Prepare responses for: +- **Denial:** [De-escalating response] +- **Deflection:** [Redirect response] +- **Emotional reaction:** [Calming response] +- **Counter-accusation:** [Non-defensive response] + +### 5. Clarify and Solve + +- State shared goals +- Present options with trade-offs +- Agree on commitments +- Assign owner and timeline +- Schedule follow-up + +## Self-Management Checklist + +- [ ] Deep breaths before starting +- [ ] Slow speaking pace +- [ ] Use pauses deliberately +- [ ] Notice body tension +- [ ] Stay curious, not defensive + +## Output + +- 1-page prep doc +- Opening lines (3-5) +- Questions list +- Reactions/responses table +- Close and next steps +- Escalation flags (if HR/compliance needed) + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/difficult-conversations/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/difficult-conversations/agents/openai.yaml new file mode 100644 index 0000000..9129c07 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/difficult-conversations/agents/openai.yaml @@ -0,0 +1,5 @@ +name: difficult-conversations +description: Prepare for challenging conversations using Prepare-Listen-Empathize-Clarify-Solve framework. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/executive-update-review/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/executive-update-review/SKILL.md new file mode 100644 index 0000000..2632415 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/executive-update-review/SKILL.md @@ -0,0 +1,47 @@ +--- +name: executive-update-review +description: Improve executive updates for clarity, decision impact, and concise speaking flow. +--- + +# Executive Update Review + +Turn a draft update into a decision-ready executive communication. + +## Instructions + +### Step 1: Rewrite TLDR +- Exactly 3 bullets: what is wanted, why now, what changes. + +### Step 2: Diagnose issues and fixes +- Provide issue -> fix table. + +### Step 3: Rebuild narrative +- Hook, stakes, options with tradeoffs, recommendation, ask. + +### Step 4: Rewrite core section +- Plain language, <=200 words. + +### Step 5: Produce speaking notes +- Opening 15s, body 2m30s, close 15s. +- Include one story/data point, one risk, one clear ask. + +### Step 6: Improve slide economy +- Recommend cuts/merges. +- Provide one-slide executive summary layout. + +## Output + +- TLDR (3 bullets) +- Issue -> fix table +- Narrative structure +- Core rewrite +- 3-minute speaking notes +- Slide economy + one-slide layout + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/executive-update-review/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/executive-update-review/agents/openai.yaml new file mode 100644 index 0000000..00a02d1 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/executive-update-review/agents/openai.yaml @@ -0,0 +1,5 @@ +name: executive-update-review +description: Improve executive updates for clarity, decision impact, and concise speaking flow. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/experiment-design/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/experiment-design/SKILL.md new file mode 100644 index 0000000..7850790 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/experiment-design/SKILL.md @@ -0,0 +1,62 @@ +--- +name: experiment-design +description: Design robust experiments to test product hypotheses. Define metrics, sample size, and success criteria. +--- + +# Experiment Design + +Design robust experiments to test product hypotheses. + +## When to Use + +When you have a hypothesis and need to design an experiment to validate it. + +## The Process + +### 1. Factor Breakdown + +Analyze your goal and system: +- What factors could influence the outcome? +- Which are controllable vs. environmental? +- What are the key variables? + +### 2. Experiment Structure + +For each factor, define: +- **Hypothesis:** What you expect to happen +- **Independent variable:** What you're changing +- **Dependent variable:** What you're measuring +- **Control group:** Baseline comparison +- **Experimental group:** Who gets the change +- **Measurement method:** How you'll collect data +- **Confounding variables:** What else could affect results + +### 3. Sample Design +- Who participates? +- How many needed for statistical significance? +- How will you recruit/select? + +### 4. Timeline +- How long to run? +- When to check results? +- What's the minimum detectable effect? + +### 5. Stop/Scale Rules +- What results mean "stop"? +- What results mean "scale"? +- What's inconclusive? + +## Output Format + +For each experiment: +- Hypothesis statement +- Variables (independent, dependent) +- Groups (control, experimental) +- Sample size and selection +- Measurement approach +- Success criteria +- Stop/scale rules + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/experiment-design/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/experiment-design/agents/openai.yaml new file mode 100644 index 0000000..98915b1 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/experiment-design/agents/openai.yaml @@ -0,0 +1,5 @@ +name: experiment-design +description: Design robust experiments to test product hypotheses. Define metrics, sample size, and success criteria. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/frontend-design/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/frontend-design/SKILL.md new file mode 100644 index 0000000..07603d5 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/frontend-design/SKILL.md @@ -0,0 +1,91 @@ +--- +name: frontend-design +description: Design implementation-ready frontend solutions with UX intent, component structure, responsive behavior, accessibility, and handoff criteria. +--- + +# Frontend Design + +Use this skill to design frontend behavior and UI structure before or alongside implementation. + +## The Process + +### Step 1: Define UX objective + +Capture: +- user goal +- primary user flow +- success state and failure states + +### Step 2: Specify UI architecture + +Define: +- screen/layout structure +- component hierarchy +- state model (loading, empty, error, success) + +### Step 3: Specify design system decisions + +Set: +- typography and spacing rules +- color/contrast constraints +- interaction patterns + +### Step 4: Specify responsive and accessibility requirements + +Include: +- breakpoints and behavior changes +- keyboard navigation expectations +- ARIA/semantic requirements +- contrast and focus visibility requirements + +### Step 5: Define implementation handoff + +Provide: +- component list and props/state contract +- acceptance criteria +- verification checklist + +## Output Format + +```markdown +# [Feature Name] Frontend Design Spec + +## UX Objective +- User goal: +- Primary flow: +- Success/failure states: + +## UI Architecture +- Layout: +- Component hierarchy: +- State model: + +## Responsive Behavior +- Desktop: +- Tablet: +- Mobile: + +## Accessibility Requirements +- Keyboard: +- Semantics/ARIA: +- Contrast/focus: + +## Handoff +- Components to implement: +- Acceptance criteria: +- Verification checklist: +``` + +## Quality Bar + +- Design decisions must map to user goals +- Accessibility section is mandatory +- Handoff must be implementable without extra interpretation + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/frontend-design/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/frontend-design/agents/openai.yaml new file mode 100644 index 0000000..5d5d4e9 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/frontend-design/agents/openai.yaml @@ -0,0 +1,5 @@ +name: frontend-design +description: Design implementation-ready frontend solutions with UX intent, component structure, responsive behavior, accessibility, and handoff criteria. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/google-calendar-schedule-check/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/google-calendar-schedule-check/SKILL.md new file mode 100644 index 0000000..56b5210 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/google-calendar-schedule-check/SKILL.md @@ -0,0 +1,79 @@ +--- +name: google-calendar-schedule-check +description: Check Google Calendar for today's schedule. Use during daily planning or when user asks about their calendar. +--- + +# Calendar Schedule Check + +Check today's calendar and factor meetings into daily planning. + +## Instructions + +### Step 1: Fetch Today's Events + +Call `calendar_list_events` for today's date range. + +### Step 2: Categorize Events + +Group events by type: +- **Meetings** - Events with other attendees +- **Focus blocks** - Solo blocked time +- **External** - Events outside work calendar + +### Step 3: Calculate Available Time + +``` +Today's Schedule: + +09:00-10:00 Team standup (meeting) +11:00-12:00 1:1 with Sarah (meeting) +14:00-15:00 Focus time (blocked) + +Available for deep work: +- 10:00-11:00 (1 hour) +- 12:00-14:00 (2 hours) +- 15:00-17:00 (2 hours) + +Total: 5 hours available +``` + +### Step 4: Factor into Task Planning + +When recommending tasks: +- Match task estimated_time to available slots +- Prioritize P0/P1 tasks for longer blocks +- Suggest quick tasks for short gaps + +### Step 5: Offer Calendar Actions + +| Option | Description | +|--------|-------------| +| Block time | Reserve time for specific task | +| Reschedule | Move a meeting if needed | +| Continue | Proceed with task planning | + +## Example Flow + +**User:** "What should I work on today?" + +**Agent:** +1. Checks calendar +2. "You have 3 meetings today, 5 hours free..." +3. Shows schedule overview +4. Recommends tasks that fit available time +5. Offers to block time for priority tasks + +## Notes + +- Respect existing focus blocks +- Consider meeting prep time +- Account for lunch/breaks +- Warn if schedule is overloaded + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/google-calendar-schedule-check/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/google-calendar-schedule-check/agents/openai.yaml new file mode 100644 index 0000000..5d453ce --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/google-calendar-schedule-check/agents/openai.yaml @@ -0,0 +1,5 @@ +name: google-calendar-schedule-check +description: Check Google Calendar for today's schedule. Use during daily planning or when user asks about their calendar. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/granola-meeting-sync/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/granola-meeting-sync/SKILL.md new file mode 100644 index 0000000..6c076c9 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/granola-meeting-sync/SKILL.md @@ -0,0 +1,79 @@ +--- +name: granola-meeting-sync +description: Sync new Granola meetings to local Knowledge folder. Use during daily planning, when user asks "what should I do today", or asks to review/sync meetings. +--- + +# Meeting Sync + +Check for new Granola meetings and offer to sync them to your local Knowledge/transcripts folder. + +## Instructions + +### Step 1: Check for New Meetings + +Call the `check_new_meetings` tool via the Granola MCP to see unsynced meetings. + +### Step 2: Present Results + +If new meetings are found, present them to the user: + +``` +I found X new meeting(s) since your last sync: + +1. **Meeting Title** (Date) +2. **Meeting Title** (Date) +... + +Add to Knowledge folder? +``` + +### Step 3: Ask User for Selection + +Ask the user to choose one option: + +| Option | Description | +|--------|-------------| +| Sync all | Add all new meetings to Knowledge/transcripts | +| Select specific | Let user choose which meetings to sync | +| Skip for now | Continue without syncing | + +### Step 4: Sync Selected Meetings + +For each meeting the user wants to sync: +1. Call `sync_meeting_to_local` with the meeting ID +2. Confirm each sync completed + +### Step 5: Continue with Daily Flow + +After syncing (or skipping), continue with the normal daily planning workflow: +- Check tasks +- Review priorities +- Suggest focus items for the day + +## Example Flow + +**User:** "What should I do today?" + +**Agent:** +1. Calls `check_new_meetings` +2. "I found 3 new meetings since your last sync..." +3. Asks the user which meetings to sync +4. User selects "Sync all" or specific meetings +5. Syncs selected meetings +6. "Synced 3 meetings. Now for your day..." +7. Continues with task planning + +## Notes + +- Only Granola meetings with notes/content are worth syncing +- Meetings marked "(no notes)" may be empty placeholders +- Sync state is tracked in `Knowledge/.granola-sync.json` +- Files are saved to `Knowledge/transcripts/` with sanitized filenames + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/granola-meeting-sync/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/granola-meeting-sync/agents/openai.yaml new file mode 100644 index 0000000..5469ffc --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/granola-meeting-sync/agents/openai.yaml @@ -0,0 +1,5 @@ +name: granola-meeting-sync +description: Sync new Granola meetings to local Knowledge folder. Use during daily planning, when user asks "what should I do today", or asks to review/sync meetings. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/hidden-agendas/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/hidden-agendas/SKILL.md new file mode 100644 index 0000000..5254907 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/hidden-agendas/SKILL.md @@ -0,0 +1,71 @@ +--- +name: hidden-agendas +description: Identify potential hidden agendas of stakeholders. Use before high-stakes meetings with complex motivations. +--- + +# Hidden Agenda Analysis + +Identify potential hidden agendas of stakeholders before important meetings. + +## When to Use + +Before high-stakes meetings where stakeholder motivations may be complex. + +## Analysis Factors + +Consider for each stakeholder: + +**Official Position** +- Their stated role/stance + +**Potential Interests** +- Financial interests +- Power dynamics +- Reputation management +- Career advancement +- Ideological beliefs +- Personal relationships +- Organizational politics + +**Historical Context** +- Past behaviors +- Previous positions +- Track record + +**Relationships** +- Alliances with other stakeholders +- Conflicts or tensions +- Dependencies + +**Outcome Analysis** +- What do they gain from different outcomes? +- What do they lose? + +## The Process + +1. List all stakeholders involved +2. Document their official position +3. Analyze potential hidden motivations +4. Identify supporting factors for your analysis +5. Consider how agendas might interact or conflict + +## Output Format + +For each stakeholder: +- Name +- Official position +- Potential hidden agenda +- Supporting factors + +Plus: Overall situation summary showing how agendas interact. + +## Principles + +- Base analysis on provided information and reasonable inference +- Avoid unfounded speculation +- Consider multiple possibilities +- Stay objective and impartial + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/hidden-agendas/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/hidden-agendas/agents/openai.yaml new file mode 100644 index 0000000..6a5081a --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/hidden-agendas/agents/openai.yaml @@ -0,0 +1,5 @@ +name: hidden-agendas +description: Identify potential hidden agendas of stakeholders. Use before high-stakes meetings with complex motivations. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/hypothesis-design/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/hypothesis-design/SKILL.md new file mode 100644 index 0000000..64cdce6 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/hypothesis-design/SKILL.md @@ -0,0 +1,62 @@ +--- +name: hypothesis-design +description: Formulate clear, testable hypotheses for product experiments. Use when designing experiments to validate solutions. +--- + +# Product Hypothesis Design + +Formulate clear, testable hypotheses for product experiments. + +## When to Use + +When you have a product problem and need to design an experiment to validate a solution. + +## The Process + +### 1. Identify the Experiment Goal +- What user problem are you addressing? +- What change do you think will help? + +### 2. Draft Hypothesis Statement + +Use this structure: +``` +[Action] will cause [Outcome] to [Direction] for [Users] under [Conditions] +``` + +All 5 components required: +- **Action:** What you're doing +- **Outcome:** What metric changes +- **Direction:** Increase/decrease/improve +- **Users:** Who's affected +- **Conditions:** When/where this applies + +### 3. Check for Specificity +- Is the action clearly defined? +- Is the outcome measurable? +- Are users and conditions specific? + +### 4. Develop Measurement Plan +- What metrics prove success? +- How will you collect data? +- What's the sample size? + +### 5. Narrative Check + +Convert to story format: +``` +Currently, [user] is experiencing [problem]. +We believe that by [change], we'll see [outcome]. +We'll know we're right when [metric] changes by [amount]. +``` + +## Quality Check + +- Is the hypothesis falsifiable? +- Can you measure the outcome? +- Is the timeframe realistic? +- Are success criteria clear? + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/hypothesis-design/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/hypothesis-design/agents/openai.yaml new file mode 100644 index 0000000..458a903 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/hypothesis-design/agents/openai.yaml @@ -0,0 +1,5 @@ +name: hypothesis-design +description: Formulate clear, testable hypotheses for product experiments. Use when designing experiments to validate solutions. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/ideas-summary/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/ideas-summary/SKILL.md new file mode 100644 index 0000000..56156db --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/ideas-summary/SKILL.md @@ -0,0 +1,65 @@ +--- +name: ideas-summary +description: Summarize meetings using IDEAS framework - Insights, Decisions, Engagements, Actions, Summary. Use after any meeting. +--- + +# IDEAS Meeting Summary + +Summarize meetings using the IDEAS framework for clear, actionable notes. + +## When to Use + +After any meeting to create a structured summary. + +## The Framework + +**IDEAS = Insights, Decisions, Engagements, Actions, Summary** + +| Component | What to Capture | +|-----------|-----------------| +| **Insights** | Key realizations, important information surfaced | +| **Decisions** | Choices made during the meeting | +| **Engagements** | Tasks/responsibilities assigned to people | +| **Actions** | Immediate next steps needed | +| **Summary** | Overall impact and significance | + +## The Process + +1. Review the meeting transcript/notes +2. Extract items for each category +3. Use bullet points for clarity +4. Focus on most important points (not every detail) + +## Output Format + +``` +## Insights +- [Key realization 1] +- [Key realization 2] + +## Decisions +- [Decision made] +- [Decision made] + +## Engagements +- [Person]: [Responsibility assigned] +- [Person]: [Responsibility assigned] + +## Actions +- [Immediate action needed] +- [Immediate action needed] + +## Summary +[1-2 sentences on meeting's impact and significance] +``` + +## Quality Check + +- Are all decisions captured? +- Do engagements have clear owners? +- Are actions specific and immediate? +- Would someone who missed the meeting understand what happened? + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/ideas-summary/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/ideas-summary/agents/openai.yaml new file mode 100644 index 0000000..3d4a891 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/ideas-summary/agents/openai.yaml @@ -0,0 +1,5 @@ +name: ideas-summary +description: Summarize meetings using IDEAS framework - Insights, Decisions, Engagements, Actions, Summary. Use after any meeting. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/influence-strategies/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/influence-strategies/SKILL.md new file mode 100644 index 0000000..1e8636f --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/influence-strategies/SKILL.md @@ -0,0 +1,56 @@ +--- +name: influence-strategies +description: Generate influence strategies using Cialdini's seven principles. Use when you need to influence toward an outcome. +--- + +# Influence Strategies (Cialdini) + +Generate influence strategies using Cialdini's seven principles. + +## When to Use + +When you need to influence a stakeholder or group toward a specific outcome. + +## The Seven Principles + +| Principle | Core Idea | Application | +|-----------|-----------|-------------| +| **Reciprocity** | People return favors | Give first, then ask | +| **Liking** | People say yes to those they like | Build rapport, find common ground | +| **Unity** | Shared identity creates connection | Emphasize "we" and shared goals | +| **Authority** | People defer to experts | Demonstrate expertise, cite credible sources | +| **Social Proof** | People follow others | Show what peers/competitors do | +| **Consistency** | People honor commitments | Get small yeses before big asks | +| **Scarcity** | Limited = valuable | Highlight unique opportunity, deadlines | + +## The Process + +### 1. Define Your Context +- Who are you trying to influence? +- What outcome do you want? +- What's their current position? + +### 2. Generate Ideas for Each Principle + +For each of the seven, create at least one strategy: +- **Strategy:** What specifically to do +- **Rationale:** Why it works for this situation + +### 3. Select Best Approaches + +Prioritize strategies that: +- Fit the context naturally +- Are ethical and professional +- Create value for both parties +- Build long-term relationship + +## Principles + +- Focus on positive influence, not manipulation +- Create genuine value for both parties +- Maintain professional ethics +- Build relationships, not just transactions + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/influence-strategies/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/influence-strategies/agents/openai.yaml new file mode 100644 index 0000000..ac445be --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/influence-strategies/agents/openai.yaml @@ -0,0 +1,5 @@ +name: influence-strategies +description: Generate influence strategies using Cialdini's seven principles. Use when you need to influence toward an outcome. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/interview-cleanup/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/interview-cleanup/SKILL.md new file mode 100644 index 0000000..a8b10ab --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/interview-cleanup/SKILL.md @@ -0,0 +1,43 @@ +--- +name: interview-cleanup +description: Clean up raw interview transcripts while preserving meaning and speaker voice. Use after conducting interviews. +--- + +# Interview Transcript Cleanup + +Clean up raw interview transcripts while preserving meaning and speaker voice. + +## When to Use + +After conducting user interviews when you have raw transcripts that need cleanup before analysis. + +## The Process + +1. **Read the full transcript** to understand context and flow + +2. **Remove noise without losing meaning:** + - Filler words (um, uh, like, you know) + - False starts (incomplete/abandoned sentences) + - Redundancies (repeated words that don't add meaning) + +3. **Preserve what matters:** + - Original meaning and intent + - Speaker's unique voice and style + - Speaker labels (Interviewer:, Interviewee:) + - Unclear/inaudible markers [inaudible] + +4. **Light editing only:** + - Fix punctuation and capitalization + - Don't over-formalize casual language + - Don't cut unnecessarily + +## Quality Check + +- Does the cleaned transcript read naturally? +- Is the original meaning preserved? +- Can you still hear the speaker's voice? +- Are all speakers clearly labeled? + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/interview-cleanup/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/interview-cleanup/agents/openai.yaml new file mode 100644 index 0000000..64e0378 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/interview-cleanup/agents/openai.yaml @@ -0,0 +1,5 @@ +name: interview-cleanup +description: Clean up raw interview transcripts while preserving meaning and speaker voice. Use after conducting interviews. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/jtbd-clustering/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/jtbd-clustering/SKILL.md new file mode 100644 index 0000000..26a9976 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/jtbd-clustering/SKILL.md @@ -0,0 +1,45 @@ +--- +name: jtbd-clustering +description: Cluster forces from multiple JTBD interviews to identify patterns. Use after extracting from multiple interviews. +--- + +# JTBD Forces Clustering + +Cluster and categorize forces from multiple interviews for pattern analysis. + +## When to Use + +When you have JTBD extractions from multiple interviews and need to identify patterns across them. + +## The Process + +1. **Create a matrix:** + - Rows = interview stories + - Columns = distinct forces + +2. **Code each interview:** + - Start with first story's forces as initial columns + - For each new story: + - If force matches existing column: mark "1" + - If force is novel: add new column + +3. **Abstraction pass:** + - Review columns for grouping opportunities + - Rename with overarching descriptors + - Merge similar forces + +4. **Analysis questions:** + - Which forces appear most frequently? + - Which stories introduced unique forces? + - What patterns emerge across segments? + +## Output + +1. **Spreadsheet summary:** Number of stories and forces identified +2. **Force categories:** Abstract labels for each column +3. **Unique contributors:** Stories that introduced novel forces +4. **Patterns and insights:** Notable observations + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/jtbd-clustering/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/jtbd-clustering/agents/openai.yaml new file mode 100644 index 0000000..53251fe --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/jtbd-clustering/agents/openai.yaml @@ -0,0 +1,5 @@ +name: jtbd-clustering +description: Cluster forces from multiple JTBD interviews to identify patterns. Use after extracting from multiple interviews. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/jtbd-extraction/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/jtbd-extraction/SKILL.md new file mode 100644 index 0000000..30d595d --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/jtbd-extraction/SKILL.md @@ -0,0 +1,57 @@ +--- +name: jtbd-extraction +description: Analyze interviews using Jobs to Be Done framework. Extract push, pull, anxiety, and habit forces. +--- + +# JTBD Extraction from Interviews + +Analyze interview transcripts using the Jobs to Be Done framework to understand why people make changes. + +## When to Use + +When analyzing customer interviews to understand decision-making and switching behavior. + +## The Framework + +JTBD breaks decisions into four forces: + +| Force | What it captures | How to phrase | +|-------|------------------|---------------| +| **Pushes** | Pain with current situation | "When..." statements | +| **Pulls** | Desired outcomes | "So I can..." or "So I don't..." | +| **Habits** | Comfort with status quo | "When..." (positive aspects) | +| **Anxieties** | Fears about change | Questions or concerns | + +## The Process + +1. **Read the transcript** looking for moments of change or decision + +2. **Extract statements** for each force: + - Pushes: "When I'm not listened to..." + - Pulls: "So I can work with someone who trusts me..." + - Habits: "When I really like my current community..." + - Anxieties: "Can this really be fixed?" + +3. **Capture context:** + - Current situation + - Job/role + - Key challenges + +4. **Synthesize insights:** + - What's driving potential change? + - What's holding them back? + - What outcome do they really want? + +## Output Format + +Provide: +- Context summary +- Pushes (list) +- Pulls (list) +- Habits (list) +- Anxieties (list) +- Key insights about decision-making + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/jtbd-extraction/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/jtbd-extraction/agents/openai.yaml new file mode 100644 index 0000000..cca8859 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/jtbd-extraction/agents/openai.yaml @@ -0,0 +1,5 @@ +name: jtbd-extraction +description: Analyze interviews using Jobs to Be Done framework. Extract push, pull, anxiety, and habit forces. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/limit-based-strategy/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/limit-based-strategy/SKILL.md new file mode 100644 index 0000000..fc6ccd4 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/limit-based-strategy/SKILL.md @@ -0,0 +1,51 @@ +--- +name: limit-based-strategy +description: Develop a limit-based product strategy with convergence milestones, acceleration levers, assumptions, and phased execution. +--- + +# Limit-Based Strategy + +Use limit-based thinking to move from problem statement to execution plan. + +## Instructions + +### Step 1: Define growth variable and limit state +- Identify the primary growth variable. +- Describe the mature limit state clearly. + +### Step 2: Identify core properties +- List features and dynamics that must exist at the limit. + +### Step 3: Estimate convergence +- Provide milestones at 10%, 25%, 50%, 75%, and 90% with dates/triggers. + +### Step 4: Identify acceleration levers +- List levers to steepen convergence. +- Prioritize top 1-2 highest impact levers. + +### Step 5: List critical assumptions +- Capture assumptions and how each will be validated. + +### Step 6: Produce execution design +- One-sentence vision. +- Major roadmap milestones. +- 3-phase plan: Foundation, Acceleration, Optimization. +- Resource guidance. + +## Output + +- Growth variable +- Limit state +- Core properties +- Convergence estimate +- Acceleration strategies +- Critical assumptions + validation +- Vision and phased execution + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/limit-based-strategy/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/limit-based-strategy/agents/openai.yaml new file mode 100644 index 0000000..d4d4c5b --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/limit-based-strategy/agents/openai.yaml @@ -0,0 +1,5 @@ +name: limit-based-strategy +description: Develop a limit-based product strategy with convergence milestones, acceleration levers, assumptions, and phased execution. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/linear-issue-sync/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/linear-issue-sync/SKILL.md new file mode 100644 index 0000000..fac3d86 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/linear-issue-sync/SKILL.md @@ -0,0 +1,84 @@ +--- +name: linear-issue-sync +description: Sync Linear issues with local tasks. Use during daily planning or when user asks about Linear issues. +--- + +# Linear Issue Sync + +Check Linear for assigned issues and sync with local task management. + +## Instructions + +### Step 1: Fetch Assigned Issues + +Call `linear_list_issues` filtered to: +- Assigned to current user +- Status not "Done" or "Canceled" + +### Step 2: Compare with Local Tasks + +Check `Tasks/` for existing files with Linear references: +- Look for `linear_id` in YAML frontmatter +- Identify new issues not yet in Tasks/ + +### Step 3: Present Summary + +``` +Linear Issues (5 active): + +**High Priority** +- LIN-123: Fix authentication timeout [In Progress] +- LIN-124: Update API documentation [Todo] + +**Normal Priority** +- LIN-125: Refactor user service [Backlog] + +2 issues not yet in local Tasks. Create them? +``` + +### Step 4: Sync Options + +| Option | Description | +|--------|-------------| +| Create all | Add all new issues as local tasks | +| Select specific | Choose which to sync | +| Skip | Continue without syncing | + +### Step 5: Create Local Tasks + +For each issue to sync, create task file: + +```yaml +--- +title: [Issue title] +category: technical +priority: [Map from Linear priority] +status: n +linear_id: LIN-XXX +--- +``` + +## Example Flow + +**User:** "What should I work on today?" + +**Agent:** +1. Fetches Linear issues +2. Compares with local tasks +3. "You have 3 new Linear issues..." +4. Offers to create local tasks +5. Continues with planning + +## Notes + +- Map Linear priorities to P0-P3 +- Keep `linear_id` in frontmatter for bidirectional sync +- Update Linear status when local task completes + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/linear-issue-sync/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/linear-issue-sync/agents/openai.yaml new file mode 100644 index 0000000..878a4e3 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/linear-issue-sync/agents/openai.yaml @@ -0,0 +1,5 @@ +name: linear-issue-sync +description: Sync Linear issues with local tasks. Use during daily planning or when user asks about Linear issues. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/llm-coding-guardrails/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/llm-coding-guardrails/SKILL.md new file mode 100644 index 0000000..bbf5967 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/llm-coding-guardrails/SKILL.md @@ -0,0 +1,76 @@ +--- +name: llm-coding-guardrails +description: Behavioral guardrails to reduce common LLM coding mistakes with a caution-first approach. +--- + +# LLM Coding Guardrails + +Behavioral guidelines to reduce common LLM coding mistakes. + +Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +Do not assume. Do not hide confusion. Surface tradeoffs. + +Before implementing: +- State assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them. Do not pick silently. +- If a simpler approach exists, say so. +- If something is unclear, stop and ask. + +## 2. Simplicity First + +Write the minimum code that solves the problem. Nothing speculative. + +- No features beyond what was asked. +- No abstractions for single-use code. +- No configurability that was not requested. +- No error handling for impossible scenarios. +- If code is substantially longer than needed, simplify it. + +Quality check: +- Would a senior engineer call this overcomplicated? +- If yes, simplify. + +## 3. Surgical Changes + +Touch only what is necessary. Clean up only what your change affected. + +When editing existing code: +- Do not improve adjacent code, comments, or formatting unless required. +- Do not refactor unrelated working code. +- Match existing style unless asked to change it. +- If you notice unrelated dead code, mention it. Do not delete it. + +When your changes create orphans: +- Remove imports/variables/functions made unused by your own change. +- Do not remove pre-existing dead code unless asked. + +Test: +- Every changed line must map directly to the request. + +## 4. Goal-Driven Execution + +Define success criteria and iterate until verified. + +Turn requests into verifiable goals: +- "Add validation" -> "Write tests for invalid inputs, then make them pass" +- "Fix the bug" -> "Write a test that reproduces it, then make it pass" +- "Refactor X" -> "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan with checks: +1. [Step] -> verify: [check] +2. [Step] -> verify: [check] +3. [Step] -> verify: [check] + +Strong success criteria support independent iteration. +Weak criteria (for example, "make it work") require repeated clarification. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/llm-coding-guardrails/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/llm-coding-guardrails/agents/openai.yaml new file mode 100644 index 0000000..108bbfe --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/llm-coding-guardrails/agents/openai.yaml @@ -0,0 +1,5 @@ +name: llm-coding-guardrails +description: Behavioral guardrails to reduce common LLM coding mistakes with a caution-first approach. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/mece-analysis/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/mece-analysis/SKILL.md new file mode 100644 index 0000000..af7cd53 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/mece-analysis/SKILL.md @@ -0,0 +1,64 @@ +--- +name: mece-analysis +description: Structure thinking using Mutually Exclusive, Collectively Exhaustive categories. Use when breaking down problems or ensuring complete coverage. +--- + +# MECE Analysis + +Structure thinking using Mutually Exclusive, Collectively Exhaustive categories. + +## When to Use + +When you need to break down a problem, categorize options, or ensure complete coverage. + +## The Principle + +**MECE = Mutually Exclusive, Collectively Exhaustive** + +- **Mutually Exclusive:** No overlap between categories +- **Collectively Exhaustive:** All possibilities covered + +## The Process + +### 1. Analyze Mutual Exclusivity + +For each pair of items: +- Is there any overlap? +- Could something belong to both? +- If overlap exists, redefine boundaries + +### 2. Analyze Collective Exhaustiveness + +For the whole set: +- Are there gaps? +- What scenarios aren't covered? +- What's missing? + +### 3. Create Logical Tree + +Structure as hierarchy: +- Top level: Broadest categories +- Sub-levels: More specific breakdowns +- Each level should be MECE + +## Example + +**Bad (not MECE):** +- Marketing channels: Social, Digital, Facebook, Email +- (Facebook overlaps with Social and Digital) + +**Good (MECE):** +- Marketing channels: Paid, Owned, Earned + - Paid: Social ads, Search ads, Display + - Owned: Email, Website, App + - Earned: PR, Reviews, Word of mouth + +## Output + +- MECE categories with clear boundaries +- Logical tree showing hierarchy +- Notes on any gaps or overlaps found + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/mece-analysis/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/mece-analysis/agents/openai.yaml new file mode 100644 index 0000000..ff6107e --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/mece-analysis/agents/openai.yaml @@ -0,0 +1,5 @@ +name: mece-analysis +description: Structure thinking using Mutually Exclusive, Collectively Exhaustive categories. Use when breaking down problems or ensuring complete coverage. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/meeting-power-dynamics/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/meeting-power-dynamics/SKILL.md new file mode 100644 index 0000000..7485c1d --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/meeting-power-dynamics/SKILL.md @@ -0,0 +1,36 @@ +--- +name: meeting-power-dynamics +description: Map meeting-specific power dynamics, influence ranking, and tactical recommendations. +--- + +# Meeting Power Dynamics + +Analyze who influences outcomes in a specific meeting context. + +## Instructions + +### Step 1: Map influence +- Rank attendees by influence for this meeting. +- Separate formal authority and informal influence. + +### Step 2: Capture observations +- Identify alliances, conflict points, and imbalance risks. +- Note likely decision-makers and blockers. + +### Step 3: Recommend tactics +- Provide concrete strategies for navigating dynamics. +- Tie recommendations to specific attendees and situations. + +## Output + +- Power map with influence order and rationale +- Key observations +- Strategic recommendations + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/meeting-power-dynamics/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/meeting-power-dynamics/agents/openai.yaml new file mode 100644 index 0000000..a3f3eef --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/meeting-power-dynamics/agents/openai.yaml @@ -0,0 +1,5 @@ +name: meeting-power-dynamics +description: Map meeting-specific power dynamics, influence ranking, and tactical recommendations. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/message-framing-comms/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/message-framing-comms/SKILL.md new file mode 100644 index 0000000..fe1fa0f --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/message-framing-comms/SKILL.md @@ -0,0 +1,47 @@ +--- +name: message-framing-comms +description: Design audience-specific framing, drafts, and communication sequence for stakeholder updates. +--- + +# Message Framing And Comms + +Create concise, audience-aware messaging and rollout plan. + +## Instructions + +### Step 1: Generate framing options +- Provide 2-3 framing options. +- Include one-line rationale for each. + +### Step 2: Draft IC communication +- Subject/headline. +- Draft <=180 words. +- Slack announcement and reminder snippets. + +### Step 3: Draft executive communication +- Subject/headline. +- Draft <=120 words. +- Slack announcement and reminder snippets. + +### Step 4: Build mini comms plan +- Table: step, channel, owner, timing, emphasis, CTA. + +### Step 5: Noise reduction and success signals +- What to omit list. +- Exactly 3 measurable success signals. + +## Output + +- Frames and rationale +- IC draft + snippets +- Executive draft + snippets +- Mini comms plan +- Omit list + 3 success signals + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/message-framing-comms/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/message-framing-comms/agents/openai.yaml new file mode 100644 index 0000000..8a34b09 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/message-framing-comms/agents/openai.yaml @@ -0,0 +1,5 @@ +name: message-framing-comms +description: Design audience-specific framing, drafts, and communication sequence for stakeholder updates. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/opportunity-solution-tree/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/opportunity-solution-tree/SKILL.md new file mode 100644 index 0000000..24143aa --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/opportunity-solution-tree/SKILL.md @@ -0,0 +1,87 @@ +--- +name: opportunity-solution-tree +description: Transform research into Opportunity Solution Tree (Teresa Torres method). Map outcomes, opportunities, solutions, and experiments. +--- + +# Opportunity Solution Tree (OST) + +Transform interview data into a structured Opportunity Solution Tree following Teresa Torres's method. + +## When to Use + +When synthesizing user research into a structured view of opportunities. + +## Key Concepts + +**Opportunity:** A customer need, pain, or desire - phrased from user perspective, not a solution. + +**Moment in time:** A distinct point in the customer journey. + +**Tests:** +- **Distinctness (siblings):** Can we pursue one without addressing the other? If yes, they're distinct. +- **Parent-child:** Does solving the child partially solve the parent? If not, reframe. + +## The Process + +### 1. Extract Opportunities + +From interviews, capture: +- Verbatim quotes +- Reframed user-need statement +- Which journey moment it belongs to + +### 2. Organize by Journey Moments + +Group opportunities under their primary moment in time. + +### 3. Structure Within Each Moment + +- Cluster similar opportunities +- Create parent nodes where needed +- Run distinctness checks across siblings +- Run parent-child checks down branches +- Remove generic parents with single children +- Combine near-duplicates + +### 4. Track Evidence + +For each opportunity, capture: +- Representative quotes +- Frequency count +- Confidence level (low/med/high) + +### 5. Prioritize Leaves + +Score leaf opportunities: +- Impact (1-5) +- Frequency (1-5) +- Alignment to outcome (1-5) +- Priority = Impact x Frequency x Alignment + +## Output Format + +**Opportunity Inventory Table:** +| ID | Moment | Opportunity | Parent ID | Quotes | Frequency | Confidence | + +**Tree View (per moment):** +``` +## [Moment Name] +- [Parent opportunity] + - [Child opportunity] + - [Grandchild] +``` + +**Prioritized Leaf Backlog:** +Ranked list with scores and rationale. + +## Rules + +- All opportunities from user perspective +- No solutions in the tree +- Keep distinct across siblings +- Prefer specific over generic +- Preserve verbatim quotes for evidence + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/opportunity-solution-tree/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/opportunity-solution-tree/agents/openai.yaml new file mode 100644 index 0000000..0820e6c --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/opportunity-solution-tree/agents/openai.yaml @@ -0,0 +1,5 @@ +name: opportunity-solution-tree +description: Transform research into Opportunity Solution Tree (Teresa Torres method). Map outcomes, opportunities, solutions, and experiments. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/ost-intake/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/ost-intake/SKILL.md new file mode 100644 index 0000000..66338b1 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/ost-intake/SKILL.md @@ -0,0 +1,40 @@ +--- +name: ost-intake +description: Normalize and collect complete Opportunity Solution Tree inputs before OST synthesis. +--- + +# OST Intake + +Collect high-quality, normalized inputs for OST work. + +## Instructions + +### Step 1: Parse existing context first +- Use provided context before asking questions. + +### Step 2: Collect four required fields +- `business_outcome` +- `journey_nodes_as_list` (JSON array of moments) +- `interview_transcripts_or_story_snippets` +- `constraints_or_principles` (or `None stated`) + +### Step 3: Normalize quality +- Reframe solution-flavored outcomes into measurable outcomes. +- Reframe feature-like nodes into moments in time. +- Add minimal attribution to transcript snippets when possible. + +### Step 4: Ask only missing critical questions +- Ask concise questions only for missing required inputs. +- Stop when all four fields are complete and clear. + +## Output + +- Final normalized values for all four required fields. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/ost-intake/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/ost-intake/agents/openai.yaml new file mode 100644 index 0000000..5b06adb --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/ost-intake/agents/openai.yaml @@ -0,0 +1,5 @@ +name: ost-intake +description: Normalize and collect complete Opportunity Solution Tree inputs before OST synthesis. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/ost-target-selection/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/ost-target-selection/SKILL.md new file mode 100644 index 0000000..209e7db --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/ost-target-selection/SKILL.md @@ -0,0 +1,47 @@ +--- +name: ost-target-selection +description: Select one target opportunity from an OST using evidence-based weighted scoring and tie-breakers. +--- + +# OST Target Selection + +Choose exactly one opportunity to pursue next. + +## Instructions + +### Step 1: Harvest candidates from OST +- Include leaves and relevant parents with strong evidence. +- Merge duplicates and reframe solution language into need language. + +### Step 2: Score candidates +- Score 1-5 for OS, MF, CF, CuF. +- Use default weights unless custom weights are provided. +- Compute weighted priority score (WPS). + +### Step 3: Build shortlist +- Select top 3-5 by WPS. +- Apply tie-breakers: distinctness, evidence quality, time-to-learning, risk diversification. + +### Step 4: Recommend one target +- Pick one small, distinct, moment-scoped opportunity. +- Exclude engineering effort prioritization. + +### Step 5: Audit alignment +- Confirm no-effort-policy and moment distinctness. +- List evidence gaps and follow-up needs. + +## Output + +- Candidate inventory +- Scoring matrix with WPS +- Top 3-5 shortlist +- Single recommendation with rationale +- Audit notes + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/ost-target-selection/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/ost-target-selection/agents/openai.yaml new file mode 100644 index 0000000..b483998 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/ost-target-selection/agents/openai.yaml @@ -0,0 +1,5 @@ +name: ost-target-selection +description: Select one target opportunity from an OST using evidence-based weighted scoring and tie-breakers. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/power-map/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/power-map/SKILL.md new file mode 100644 index 0000000..462056d --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/power-map/SKILL.md @@ -0,0 +1,80 @@ +--- +name: power-map +description: Map stakeholders by power and interest to plan engagement strategy. Use when starting multi-stakeholder initiatives. +--- + +# Stakeholder Power-Interest Map + +Map stakeholders by power and interest to plan engagement strategy. + +## When to Use + +When starting an initiative that involves multiple stakeholders. + +## The Framework + +### Power-Interest Grid + +| | Low Interest | High Interest | +|---|---|---| +| **High Power** | Keep Satisfied | Manage Closely | +| **Low Power** | Monitor | Keep Informed | + +### Influence Pyramid + +Beyond formal power, map informal influence: +- **Top tier:** Decision makers, budget holders +- **Middle tier:** Gatekeepers, team leads +- **Base tier:** Super-connectors, exec assistants + +## The Process + +### 1. List Stakeholders + +Gather: +- Names and roles +- Organizational position +- Known relationships +- Allies and blockers + +### 2. Map to Grid + +Place each stakeholder in the 2x2 based on: +- **Power:** Formal authority, budget control, veto ability +- **Interest:** How much they care about this initiative + +### 3. Build Influence Pyramid + +Identify informal power: +- Who controls access? +- Who influences opinion? +- Who connects people? + +### 4. Profile High-Power Stakeholders + +For each, document: +- Goals and success metrics +- Likely concerns (political, operational, reputational) +- Preferred communication style +- Political risks for you + +### 5. Create Engagement Plan + +For each high-power stakeholder: +- Cadence and channel +- Format and owner +- Key message (tied to their priorities) +- Quick win to offer +- Fallback if they resist + +## Output + +- Power-Interest matrix with names +- Influence pyramid with rationale +- High-power profiles table +- Engagement plan table +- Top 3 political pitfalls to avoid + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/power-map/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/power-map/agents/openai.yaml new file mode 100644 index 0000000..c9b453c --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/power-map/agents/openai.yaml @@ -0,0 +1,5 @@ +name: power-map +description: Map stakeholders by power and interest to plan engagement strategy. Use when starting multi-stakeholder initiatives. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/prd-writing/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/prd-writing/SKILL.md new file mode 100644 index 0000000..7e91127 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/prd-writing/SKILL.md @@ -0,0 +1,120 @@ +--- +name: prd-writing +description: Write a structured PRD for high-risk, cross-team, or multi-sprint initiatives before implementation. +--- + +# PRD Writing + +Create clear, implementation-ready product requirements documents for initiatives that need alignment before coding. + +## The Process + +### Step 1: Confirm PRD is needed + +Use PRD only if at least one is true: +- cross-team dependency +- multi-sprint scope +- high-risk decision or expensive tradeoff +- stakeholder alignment needed before build + +If none apply, recommend execution-first flow (`writing-plans` -> `tdd` -> `verification`) instead. + +### Step 2: Gather required inputs + +Collect: +- product goal and target user +- business context and constraints +- known assumptions and risks +- success criteria and timeline + +State explicit assumptions when inputs are missing. + +### Step 3: Produce PRD in required format + +Use this exact structure: + +```markdown +# [Product Name] + +## About +[High-level overview of the product and goal.] + +## Market Insights +[Market context, competitors, trends, and target users.] + +## Problem +[Core user problem, pain points, and why existing solutions are insufficient.] + +## Solution +[Proposed AI product solution and how it addresses the problem.] + +## Feature Prioritization + +| Feature | Reach | Impact | Confidence | Effort | RICE Score | Priority | +|---------|-------|--------|------------|--------|------------|----------| +| | | | | | | | +| | | | | | | | +| | | | | | | | + +## Requirements + +**Functional Requirements:** +- FR1: +- FR2: +- FR3: + +**AI/ML Model Requirements:** +- MR1: +- MR2: +- MR3: + +**Non-Functional Requirements:** +- NFR1: +- NFR2: +- NFR3: + +## Challenges +[Key product, technical, data, and go-to-market challenges.] + +## Positioning + +| Use Case | Target User | Key Benefit | Differentiator | +|----------|-------------|-------------|----------------| +| | | | | +| | | | | +| | | | | + +## Metrics +[Success metrics and north star metric.] + +## Rollout Plan + +- **Stakeholders & Communication** + - [Stakeholder groups and communication plan] + +- **Roll-out Strategy** + - [Launch phases, gating criteria, and post-GA plan] +``` + +### Step 4: Quality checks before finalizing + +Ensure: +- no placeholder fields remain +- RICE rows are populated and prioritized +- metrics include baseline, target, and timeframe +- rollout includes phases and gating criteria +- top risks are explicit + +## Output + +- Final PRD in the required structure +- A short assumptions list +- Open questions/blockers list + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/prd-writing/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/prd-writing/agents/openai.yaml new file mode 100644 index 0000000..5080ff1 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/prd-writing/agents/openai.yaml @@ -0,0 +1,5 @@ +name: prd-writing +description: Write a structured PRD for high-risk, cross-team, or multi-sprint initiatives before implementation. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/problem-structuring/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/problem-structuring/SKILL.md new file mode 100644 index 0000000..fd22a4d --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/problem-structuring/SKILL.md @@ -0,0 +1,61 @@ +--- +name: problem-structuring +description: Break down complex problems into actionable recommendations using deductive and inductive analysis. +--- + +# Problem Structuring + +Break down complex problems into actionable recommendations. + +## When to Use + +When facing a complex, ambiguous problem that needs structured analysis. + +## The Process + +### 1. Simplify the Problem + +- Identify core components +- List key stakeholders +- Summarize in 2-3 sentences + +### 2. Deductive Analysis (Top-Down) + +Start broad, work to specifics: +- What's the general situation? +- Create logical tree of options +- Map cause-and-effect relationships +- Explore branches and outcomes + +### 3. Inductive Analysis (Bottom-Up) + +Start with specifics, find patterns: +- Examine data points and examples +- Look for patterns and trends +- What do specifics suggest about the whole? + +### 4. Synthesize + +Combine both approaches: +- Where do they agree? +- Where do they conflict? +- What insights emerge? + +### 5. Develop Recommendation + +Based on analysis: +- Clear, actionable recommendation +- Rationale tied to analysis +- Trade-offs acknowledged + +## Output Format + +- **Simplified problem:** Concise summary +- **Deductive analysis:** Logical tree with options +- **Inductive analysis:** Patterns from data +- **Synthesis:** Combined insights +- **Recommendation:** Clear action with rationale + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/problem-structuring/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/problem-structuring/agents/openai.yaml new file mode 100644 index 0000000..e011662 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/problem-structuring/agents/openai.yaml @@ -0,0 +1,5 @@ +name: problem-structuring +description: Break down complex problems into actionable recommendations using deductive and inductive analysis. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/root-cause-analysis/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/root-cause-analysis/SKILL.md new file mode 100644 index 0000000..277bc14 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/root-cause-analysis/SKILL.md @@ -0,0 +1,55 @@ +--- +name: root-cause-analysis +description: Uncover root causes through recursive Why questioning and consequence exploration. Use before acting on problems. +--- + +# Root Cause Analysis + +Uncover root causes and explore consequences through structured questioning. + +## When to Use + +When you need to deeply understand a problem, decision, or situation before acting. + +## The Process + +### 1. Recursive "Why" Questioning + +Start with the initial question and ask "Why?" repeatedly: +- Ask "Why?" at least 5 times +- Go deeper until you reach fundamental causes +- If multiple reasons emerge, explore each branch + +**Example:** +- Why did users churn? → Onboarding was confusing +- Why was it confusing? → Too many steps +- Why too many steps? → We added features without simplifying +- Why didn't we simplify? → No ownership of onboarding experience +- Why no ownership? → Org structure doesn't align to user journey + +### 2. Consequence Exploration + +After finding root causes, explore forward: +- **1st order:** Immediate consequences +- **2nd order:** What results from those? +- **3rd-5th order:** Downstream effects + +Consider both positive and negative outcomes. + +### 3. First Principles Check + +- What fundamental truths underlie this? +- What assumptions are we making? +- What alternative perspectives exist? +- Where are the gaps in logic? + +## Output Format + +- Root causes (the "Why?" chain) +- Consequences (1st through 5th order) +- First principles (fundamental truths, assumptions) +- Conclusion (key insights) + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/root-cause-analysis/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/root-cause-analysis/agents/openai.yaml new file mode 100644 index 0000000..adbdf71 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/root-cause-analysis/agents/openai.yaml @@ -0,0 +1,5 @@ +name: root-cause-analysis +description: Uncover root causes through recursive Why questioning and consequence exploration. Use before acting on problems. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/signal-identification/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/signal-identification/SKILL.md new file mode 100644 index 0000000..a089906 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/signal-identification/SKILL.md @@ -0,0 +1,66 @@ +--- +name: signal-identification +description: Design efficient early signals to validate assumptions. Find the fastest way to learn if you're right. +--- + +# Signal Identification + +Design efficient early signals to validate product assumptions. + +## When to Use + +When you have a prioritized assumption and need the fastest way to validate it. + +## The Quality Bar + +A good signal is: +- **Early:** Obtainable at idea/prototype stage +- **Cheap:** Minimal cash/time +- **Attributable:** Directly reduces uncertainty +- **Decisive:** Has clear success/failure threshold +- **Suitable:** Appropriate for your context + +## Method Selection by Context + +| Context | Good Methods | Avoid | +|---------|--------------|-------| +| **Enterprise B2B** | Design partner LOIs, security questionnaires, ROI calculators, reference checks | Smoke tests, consumer ad funnels | +| **SMB SaaS** | Discovery calls, lightweight trials, email tests, usage analytics | - | +| **Consumer** | Ad-driven intent, waitlist conversion, community polls, preorders | - | +| **Regulated** | Standards mapping, SME review, regulatory preflight | Collecting sensitive data | +| **Feasibility** | Engineering spikes, benchmarks, vendor evals | User-facing experiments | + +## The Process + +### 1. Classify the Assumption + +What lens? Desirability, Feasibility, Viability, or Usability? + +### 2. Brainstorm Signals (5+) + +For each, note: +- What would constitute positive evidence? +- How to obtain quickly? +- Why suitable for this context? + +### 3. Select Best Signal + +Document: +- Signal description +- Method (step-by-step) +- Participants/sample needed +- Timebox and cost +- Success threshold (quantified) +- Data captured +- Risks and mitigations +- What to do next if positive + +## Output + +- Brainstorm list (5+ signals) +- Selected signal with full details +- Summary explaining choice + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/signal-identification/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/signal-identification/agents/openai.yaml new file mode 100644 index 0000000..2552a21 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/signal-identification/agents/openai.yaml @@ -0,0 +1,5 @@ +name: signal-identification +description: Design efficient early signals to validate assumptions. Find the fastest way to learn if you're right. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/slack-message-check/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/slack-message-check/SKILL.md new file mode 100644 index 0000000..91db25b --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/slack-message-check/SKILL.md @@ -0,0 +1,75 @@ +--- +name: slack-message-check +description: Check Slack for important messages and activity. Use during daily planning or when user asks about Slack updates. +--- + +# Slack Message Check + +Check Slack channels for important messages and summarize activity. + +## Instructions + +### Step 1: List Relevant Channels + +Call `slack_list_channels` to see available channels. + +### Step 2: Check Priority Channels + +For each important channel (determined by user preferences or channel activity): +1. Call `slack_get_channel_history` with limit of 20 messages +2. Filter for messages since last check + +### Step 3: Summarize Activity + +Present findings to user: + +``` +Slack activity since yesterday: + +**#general** (3 new messages) +- @alice mentioned the deployment schedule + +**#engineering** (12 new messages) +- Discussion about API changes +- @bob asked for review on PR #234 + +**DMs** (2 unread) +- @carol: Question about meeting time +``` + +### Step 4: Offer Actions + +| Option | Description | +|--------|-------------| +| Create task | Turn a message into a task | +| Reply | Draft a response | +| Mark read | Continue without action | + +### Step 5: Continue Daily Flow + +After Slack check, continue with normal planning workflow. + +## Example Flow + +**User:** "What should I work on today?" + +**Agent:** +1. Checks Slack for new activity +2. "You have 5 new messages across 2 channels..." +3. Summarizes key items +4. Offers to create tasks from actionable messages +5. Continues with task planning + +## Notes + +- Focus on actionable messages, not all activity +- Prioritize DMs and mentions over general channel noise +- Respect user's channel preferences if configured + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/slack-message-check/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/slack-message-check/agents/openai.yaml new file mode 100644 index 0000000..986e724 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/slack-message-check/agents/openai.yaml @@ -0,0 +1,5 @@ +name: slack-message-check +description: Check Slack for important messages and activity. Use during daily planning or when user asks about Slack updates. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/spec-writing/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/spec-writing/SKILL.md new file mode 100644 index 0000000..3953ce1 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/spec-writing/SKILL.md @@ -0,0 +1,93 @@ +--- +name: spec-writing +description: Convert an approved PRD or clear requirements into an implementation-ready technical spec with scope, interfaces, and acceptance criteria. +--- + +# Spec Writing + +Use this skill to produce an implementation-ready spec before planning or coding. + +## The Process + +### Step 1: Validate inputs + +Require one of: +- approved PRD +- clear requirements with goals and constraints + +If inputs are missing or ambiguous, list assumptions and open questions first. + +### Step 2: Define scope boundaries + +Document: +- in scope +- out of scope +- constraints (time, dependencies, compliance, platform) + +### Step 3: Define solution design + +Specify: +- architecture overview (high-level components) +- interfaces/contracts +- data model changes +- rollout and migration approach + +### Step 4: Define acceptance and verification + +Include: +- acceptance criteria (testable) +- non-functional expectations (performance, security, reliability) +- verification commands/checks required before completion + +## Output Format + +```markdown +# [Feature Name] Technical Spec + +## Goal +[What this spec delivers and why] + +## Scope +- In scope: +- Out of scope: +- Constraints: + +## Design +- Architecture: +- Interfaces/contracts: +- Data model changes: +- Migration/rollout: + +## Risks and Dependencies +- Risks: +- Dependencies: +- Mitigations: + +## Acceptance Criteria +- AC1: +- AC2: +- AC3: + +## Verification Plan +- Required checks: +- Commands: +- Evidence to capture: + +## Open Questions +- Q1: +- Q2: +``` + +## Quality Bar + +- No vague placeholders in final output +- Acceptance criteria must be measurable +- Verification plan must include explicit commands + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/spec-writing/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/spec-writing/agents/openai.yaml new file mode 100644 index 0000000..36a3847 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/spec-writing/agents/openai.yaml @@ -0,0 +1,5 @@ +name: spec-writing +description: Convert an approved PRD or clear requirements into an implementation-ready technical spec with scope, interfaces, and acceptance criteria. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/stakeholder-risk-review/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/stakeholder-risk-review/SKILL.md new file mode 100644 index 0000000..107147f --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/stakeholder-risk-review/SKILL.md @@ -0,0 +1,47 @@ +--- +name: stakeholder-risk-review +description: Review a feature or PRD for stakeholder and political risk before broad circulation. +--- + +# Stakeholder Risk Review + +Stress-test a proposal for adoption and political risk. + +## Instructions + +### Step 1: Build snapshot +- Create power-interest matrix with named stakeholders. +- Include informal influencers. + +### Step 2: Map concerns +- For each key stakeholder: concern, evidence needed, response plan. + +### Step 3: Define mitigation plan +- Document improvements and 1:1 messaging by stakeholder. +- Provide exactly 3 pre-work actions. + +### Step 4: Define framing and sequence +- Provide separate framing for executives and ICs. +- Provide minimal communication sequence. + +### Step 5: Capture risks and readiness +- Risk table with mitigation + owner. +- Readiness checklist. + +## Output + +- Power-interest snapshot +- Stakeholder concerns table +- Document changes +- 1:1 messages +- Top 3 pre-work actions +- Framing + comms sequence +- Risks + readiness checklist + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/stakeholder-risk-review/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/stakeholder-risk-review/agents/openai.yaml new file mode 100644 index 0000000..a9caa24 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/stakeholder-risk-review/agents/openai.yaml @@ -0,0 +1,5 @@ +name: stakeholder-risk-review +description: Review a feature or PRD for stakeholder and political risk before broad circulation. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/structured-product-strategy/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/structured-product-strategy/SKILL.md new file mode 100644 index 0000000..f61cf5f --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/structured-product-strategy/SKILL.md @@ -0,0 +1,54 @@ +--- +name: structured-product-strategy +description: Build a complete product strategy from context, including objective, users, superpowers, vision, pillars, impact, and roadmap. +--- + +# Structured Product Strategy + +Create a coherent strategy from product context. + +## Instructions + +### Step 1: Define objective +- Write a 1-2 sentence objective that is ambitious and achievable. + +### Step 2: Define users and needs +- Choose 1-2 core user groups. +- List 3-4 concrete needs for each. + +### Step 3: Identify superpowers +- Name 3-4 unique advantages that can compound. + +### Step 4: Draft vision +- Write 2-3 paragraphs linking objective, users, and superpowers. + +### Step 5: Define pillars and impact +- Create 2-4 strategy pillars. +- Explain causal impact mechanism to business outcomes. + +### Step 6: Draft roadmap by pillar +- Provide 3-10 initiatives per pillar. +- Do not prioritize unless asked. + +## Output + +- Objective +- Users +- Superpowers +- Vision +- Pillars +- Impact mechanism +- Roadmap by pillar + +## Quality Bar + +- Ground every claim in provided context. +- State assumptions explicitly when context is missing. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/structured-product-strategy/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/structured-product-strategy/agents/openai.yaml new file mode 100644 index 0000000..eb50361 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/structured-product-strategy/agents/openai.yaml @@ -0,0 +1,5 @@ +name: structured-product-strategy +description: Build a complete product strategy from context, including objective, users, superpowers, vision, pillars, impact, and roadmap. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/systematic-debugging/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/systematic-debugging/SKILL.md new file mode 100644 index 0000000..539d063 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/systematic-debugging/SKILL.md @@ -0,0 +1,115 @@ +--- +name: systematic-debugging +description: Four-phase debugging process - root cause first, then fix. Use when encountering bugs or unexpected behavior. +--- + +# Systematic Debugging + +Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. + +## The Iron Law + +``` +NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST +``` + +If you haven't completed Phase 1, you cannot propose fixes. + +## The Four Phases + +### Phase 1: Root Cause Investigation + +**BEFORE attempting ANY fix:** + +1. **Read Error Messages Carefully** + - Don't skip past errors or warnings + - Read stack traces completely + - Note line numbers, file paths, error codes + +2. **Reproduce Consistently** + - Can you trigger it reliably? + - What are the exact steps? + - If not reproducible, gather more data + +3. **Check Recent Changes** + - Git diff, recent commits + - New dependencies, config changes + - Environmental differences + +4. **Trace Data Flow** + - Where does bad value originate? + - What called this with bad value? + - Keep tracing up until you find the source + +### Phase 2: Pattern Analysis + +1. **Find Working Examples** + - Locate similar working code in same codebase + +2. **Compare Against References** + - Read reference implementation completely + - Don't skim - read every line + +3. **Identify Differences** + - What's different between working and broken? + - List every difference, however small + +### Phase 3: Hypothesis and Testing + +1. **Form Single Hypothesis** + - State clearly: "I think X is the root cause because Y" + - Write it down + +2. **Test Minimally** + - Make the SMALLEST possible change + - One variable at a time + +3. **Verify Before Continuing** + - Did it work? Yes -> Phase 4 + - Didn't work? Form NEW hypothesis + - DON'T add more fixes on top + +### Phase 4: Implementation + +1. **Create Failing Test Case** + - Use the `tdd.md` skill + +2. **Implement Single Fix** + - ONE change at a time + - No "while I'm here" improvements + +3. **Verify Fix** + - Test passes now? + - No other tests broken? + +4. **If 3+ Fixes Failed: Question Architecture** + - Is this pattern fundamentally sound? + - Should we refactor vs continue fixing symptoms? + - Discuss before attempting more fixes + +## Red Flags - STOP and Follow Process + +- "Quick fix for now, investigate later" +- "Just try changing X and see if it works" +- "I don't fully understand but this might work" +- Proposing solutions before tracing data flow +- "One more fix attempt" (when already tried 2+) + +**ALL mean: STOP. Return to Phase 1.** + +## Quick Reference + +| Phase | Key Activities | Success Criteria | +|-------|---------------|------------------| +| 1. Root Cause | Read errors, reproduce, check changes | Understand WHAT and WHY | +| 2. Pattern | Find working examples, compare | Identify differences | +| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis | +| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass | + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/systematic-debugging/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/systematic-debugging/agents/openai.yaml new file mode 100644 index 0000000..6200c34 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/systematic-debugging/agents/openai.yaml @@ -0,0 +1,5 @@ +name: systematic-debugging +description: Four-phase debugging process - root cause first, then fix. Use when encountering bugs or unexpected behavior. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/tdd/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/tdd/SKILL.md new file mode 100644 index 0000000..8deb167 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/tdd/SKILL.md @@ -0,0 +1,105 @@ +--- +name: tdd +description: Test-driven development - write failing test first, then minimal code. Use before implementing any feature or bugfix. +--- + +# Test-Driven Development (TDD) + +Use when implementing any feature or bugfix, before writing implementation code. + +## The Iron Law + +``` +NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST +``` + +Write code before the test? Delete it. Start over. + +**No exceptions:** +- Don't keep it as "reference" +- Don't "adapt" it while writing tests +- Delete means delete + +## Red-Green-Refactor + +### RED - Write Failing Test +Write one minimal test showing what should happen. +- One behavior +- Clear name +- Real code (no mocks unless unavoidable) + +### Verify RED - Watch It Fail +**MANDATORY. Never skip.** +- Run the test, confirm it fails (not errors) +- Failure message is expected +- Test passes? You're testing existing behavior. Fix test. + +### GREEN - Minimal Code +Write simplest code to pass the test. +- Just enough to pass +- No extra features +- Don't add behavior beyond the test + +### Verify GREEN - Watch It Pass +**MANDATORY.** +- Test passes +- Other tests still pass +- Output pristine (no errors, warnings) + +### REFACTOR - Clean Up +After green only: +- Remove duplication +- Improve names +- Extract helpers +Keep tests green. Don't add behavior. + +## Why Order Matters + +**"I'll write tests after"** +Tests written after pass immediately. Passing immediately proves nothing. Test-first forces you to see the test fail, proving it actually tests something. + +**"Tests after achieve same goals"** +No. Tests-after answer "What does this do?" Tests-first answer "What should this do?" + +**"Deleting X hours of work is wasteful"** +Sunk cost fallacy. The time is gone. The waste is keeping code you can't trust. + +## Red Flags - STOP and Start Over + +- Code before test +- Test after implementation +- Test passes immediately +- "I already manually tested it" +- "Tests after achieve the same purpose" +- "This is different because..." + +**All mean: Delete code. Start over with TDD.** + +## Common Rationalizations + +| Excuse | Reality | +|--------|---------| +| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | +| "I'll test after" | Tests passing immediately prove nothing. | +| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. | +| "TDD will slow me down" | TDD faster than debugging later. | + +## Verification Checklist + +Before marking work complete: +- [ ] Every new function/method has a test +- [ ] Watched each test fail before implementing +- [ ] Each test failed for expected reason +- [ ] Wrote minimal code to pass each test +- [ ] All tests pass +- [ ] Output pristine (no errors, warnings) + +Can't check all boxes? You skipped TDD. Start over. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/tdd/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/tdd/agents/openai.yaml new file mode 100644 index 0000000..01bd376 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/tdd/agents/openai.yaml @@ -0,0 +1,5 @@ +name: tdd +description: Test-driven development - write failing test first, then minimal code. Use before implementing any feature or bugfix. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/value-chain-mapping/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/value-chain-mapping/SKILL.md new file mode 100644 index 0000000..10699d5 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/value-chain-mapping/SKILL.md @@ -0,0 +1,38 @@ +--- +name: value-chain-mapping +description: Map end-user needs to the full value chain, identify core value generators, and highlight vulnerabilities. +--- + +# Value Chain Mapping + +Map value creation from user needs to foundational inputs. + +## Instructions + +### Step 1: Capture end-user needs +- List primary user needs the product serves. + +### Step 2: Build value chain hierarchy +- Trace from needs -> activities -> enablers -> foundational inputs. + +### Step 3: Identify core value generators +- Mark nodes that generate defensible advantage. +- Explain why each is hard to replicate. + +### Step 4: Assess vulnerabilities +- Highlight disruption points and fragility in chain links. + +## Output + +- End-user needs +- Value chain breakdown +- Core value generators +- Potential vulnerabilities + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/value-chain-mapping/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/value-chain-mapping/agents/openai.yaml new file mode 100644 index 0000000..b0e6979 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/value-chain-mapping/agents/openai.yaml @@ -0,0 +1,5 @@ +name: value-chain-mapping +description: Map end-user needs to the full value chain, identify core value generators, and highlight vulnerabilities. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/verification/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/verification/SKILL.md new file mode 100644 index 0000000..bf8305d --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/verification/SKILL.md @@ -0,0 +1,92 @@ +--- +name: verification +description: Verify before claiming completion. No claims without fresh verification evidence. Use before marking work done. +--- + +# Verification Before Completion + +Use when about to claim work is complete, fixed, or passing. + +## The Iron Law + +``` +NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE +``` + +If you haven't run the verification command in this message, you cannot claim it passes. + +## The Gate Function + +Before claiming any status or completion: + +1. **IDENTIFY** - What command proves this claim? +2. **RUN** - Execute the FULL command (fresh, complete) +3. **READ** - Full output, check exit code, count failures +4. **VERIFY** - Does output confirm the claim? + - If NO: State actual status with evidence + - If YES: State claim WITH evidence +5. **ONLY THEN** - Make the claim + +Skip any step = lying, not verifying. + +## What Requires Verification + +| Claim | Requires | Not Sufficient | +|-------|----------|----------------| +| Tests pass | Test command output: 0 failures | Previous run, "should pass" | +| Linter clean | Linter output: 0 errors | Partial check | +| Build succeeds | Build command: exit 0 | Linter passing | +| Bug fixed | Test original symptom: passes | Code changed | +| Phase complete | All objectives verified | Tests passing | +| Task done | Checklist items verified | "I did everything" | + +## Red Flags - STOP + +- Using "should", "probably", "seems to" +- Expressing satisfaction before verification ("Great!", "Done!") +- About to commit/push without verification +- Relying on partial verification +- ANY wording implying success without having run verification + +## Patterns + +**Tests:** +``` +OK: [Run test] [See: 34/34 pass] "All tests pass" +BAD: "Should pass now" +``` + +**Build:** +``` +OK: [Run build] [See: exit 0] "Build passes" +BAD: "Linter passed" (linter != compiler) +``` + +**Task completion:** +``` +OK: Re-read requirements -> checklist -> verify each -> report +BAD: "Tests pass, task complete" +``` + +## Common Rationalizations + +| Excuse | Reality | +|--------|---------| +| "Should work now" | Run the verification | +| "I'm confident" | Confidence != evidence | +| "Just this once" | No exceptions | +| "Partial check is enough" | Partial proves nothing | + +## The Bottom Line + +Run the command. Read the output. Then claim the result. + +No shortcuts. Non-negotiable. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/verification/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/verification/agents/openai.yaml new file mode 100644 index 0000000..53973d8 --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/verification/agents/openai.yaml @@ -0,0 +1,5 @@ +name: verification +description: Verify before claiming completion. No claims without fresh verification evidence. Use before marking work done. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.agents/skills/writing-plans/SKILL.md b/examples/uj-1-node-monorepo/.agents/skills/writing-plans/SKILL.md new file mode 100644 index 0000000..7fca99c --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/writing-plans/SKILL.md @@ -0,0 +1,95 @@ +--- +name: writing-plans +description: Create comprehensive implementation plans with bite-sized tasks. Use when you have requirements before touching code. +--- + +# Writing Plans + +Use when you have requirements for a multi-step task, before touching code. + +## Overview + +Write comprehensive implementation plans assuming the reader has zero context. Document everything: which files to touch, code snippets, testing steps, verification commands. Break into bite-sized tasks. + +## Bite-Sized Task Granularity + +Each step is one action (2-5 minutes): +- "Write the failing test" - step +- "Run it to make sure it fails" - step +- "Implement the minimal code to make the test pass" - step +- "Run the tests and make sure they pass" - step +- "Commit" - step + +## Plan Document Header + +Every plan should start with: + +```markdown +# [Feature Name] Implementation Plan + +**Goal:** [One sentence describing what this builds] + +**Architecture:** [2-3 sentences about approach] + +**Tech Stack:** [Key technologies/libraries] + +--- +``` + +## Task Structure + +```markdown +### Task N: [Component Name] + +**Files:** +- Create: `exact/path/to/file.py` +- Modify: `exact/path/to/existing.py:123-145` +- Test: `tests/exact/path/to/test.py` + +**Step 1: Write the failing test** + +```python +def test_specific_behavior(): + result = function(input) + assert result == expected +``` + +**Step 2: Run test to verify it fails** + +Run: `pytest tests/path/test.py::test_name -v` +Expected: FAIL with "function not defined" + +**Step 3: Write minimal implementation** + +```python +def function(input): + return expected +``` + +**Step 4: Run test to verify it passes** + +Run: `pytest tests/path/test.py::test_name -v` +Expected: PASS + +**Step 5: Commit** + +```bash +git add tests/path/test.py src/path/file.py +git commit -m "feat: add specific feature" +``` +``` + +## Remember + +- Exact file paths always +- Complete code in plan (not "add validation") +- Exact commands with expected output +- DRY, YAGNI, TDD, frequent commits + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-1-node-monorepo/.agents/skills/writing-plans/agents/openai.yaml b/examples/uj-1-node-monorepo/.agents/skills/writing-plans/agents/openai.yaml new file mode 100644 index 0000000..030a02b --- /dev/null +++ b/examples/uj-1-node-monorepo/.agents/skills/writing-plans/agents/openai.yaml @@ -0,0 +1,5 @@ +name: writing-plans +description: Create comprehensive implementation plans with bite-sized tasks. Use when you have requirements before touching code. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-1-node-monorepo/.cursor/rules/002-dates.mdc b/examples/uj-1-node-monorepo/.cursor/rules/002-dates.mdc new file mode 100644 index 0000000..435818c --- /dev/null +++ b/examples/uj-1-node-monorepo/.cursor/rules/002-dates.mdc @@ -0,0 +1,10 @@ +--- +description: Date handling conventions +globs: src/**/*.ts +alwaysApply: true +--- +# Date Handling + +- Always use ISO 8601 format for dates +- Use dayjs for date manipulation +- Store dates in UTC, display in user's timezone diff --git a/examples/uj-1-node-monorepo/.cursor/rules/003-eslint.mdc b/examples/uj-1-node-monorepo/.cursor/rules/003-eslint.mdc new file mode 100644 index 0000000..e96dace --- /dev/null +++ b/examples/uj-1-node-monorepo/.cursor/rules/003-eslint.mdc @@ -0,0 +1,11 @@ +--- +description: ESLint configuration and style +globs: src/**/*.{ts,tsx} +alwaysApply: true +--- +# ESLint Rules + +- Follow airbnb style guide +- No unused variables (error level) +- Prefer const over let +- No console.log in production code diff --git a/examples/uj-1-node-monorepo/.cursor/rules/005-api.mdc b/examples/uj-1-node-monorepo/.cursor/rules/005-api.mdc new file mode 100644 index 0000000..3431f60 --- /dev/null +++ b/examples/uj-1-node-monorepo/.cursor/rules/005-api.mdc @@ -0,0 +1,11 @@ +--- +description: API design patterns +globs: packages/api/**/* +alwaysApply: true +--- +# API Conventions + +- RESTful endpoints follow /api/v1/{resource} pattern +- Use zod for request validation +- Return consistent error shapes: { error: string, code: number } +- All endpoints require authentication except /health diff --git a/examples/uj-1-node-monorepo/.gitignore b/examples/uj-1-node-monorepo/.gitignore new file mode 100644 index 0000000..4116dbf --- /dev/null +++ b/examples/uj-1-node-monorepo/.gitignore @@ -0,0 +1,48 @@ +# Template .gitignore for Task Management System +# Copy relevant parts to your .gitignore + +# Personal task files +Tasks/*.md +!Tasks/.gitkeep +BACKLOG.md + +# Personal configuration +AGENTS.md # If customized from template +GOALS.md # Personal goals + +# Keep templates and examples +!AGENTS_TEMPLATE.md +!Tasks/example.md + +# Python +__pycache__/ +*.py[cod] +*$py.class +.Python +venv/ +.venv/ +env/ +.env + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store + +# Logs +*.log +logs/ + +# Testing +test_*.py +*.test.py +.pytest_cache/ +.coverage + +# MCP/System +.mcp_cache/ +*.pid +*.lock \ No newline at end of file diff --git a/examples/uj-1-node-monorepo/CLAUDE.md b/examples/uj-1-node-monorepo/CLAUDE.md new file mode 100644 index 0000000..b8d798f --- /dev/null +++ b/examples/uj-1-node-monorepo/CLAUDE.md @@ -0,0 +1,6 @@ +@AGENTS.md + +## Skills + +Canonical skills are available at `.agents/skills/*/SKILL.md` (also accessible via `.claude/skills/`). +To run a skill: read its SKILL.md and follow the instructions within. diff --git a/examples/uj-1-node-monorepo/Workflows/README.md b/examples/uj-1-node-monorepo/Workflows/README.md new file mode 100644 index 0000000..ac04cda --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/README.md @@ -0,0 +1,58 @@ +# Workflows + +Reusable workflows that your AI agent invokes on demand. These are referenced from AGENTS.md and executed when relevant tasks are detected. + +## Daily Workflows + +| Workflow | Time | When to Use | +|----------|------|-------------| +| [Daily Standup](daily-standup.md) | 2 min | Start of day - pick your focus | +| [Backlog Processing](backlog-processing.md) | 5-10 min | End of day or when backlog builds up | +| [Wrap-up Protocol](wrap-up-protocol.md) | 2 min | After completing any work | + +## Weekly Workflows + +| Workflow | Time | When to Use | +|----------|------|-------------| +| [Weekly Review](weekly-review.md) | 15-30 min | Friday PM or Sunday/Monday | + +## Product & Strategy Workflows + +| Workflow | Time | When to Use | +|----------|------|-------------| +| [Research to Feature Pipeline](research-to-feature-pipeline.md) | 20-60 min | Turn interviews into testable product moves | +| [Decision Quality Pipeline](decision-quality-pipeline.md) | 15-45 min | De-risk high-impact decisions | +| [Assumption Validation Pipeline](assumption-validation-pipeline.md) | 15-45 min | Prioritize and test strategic assumptions | +| [Core Strategy Development](core-strategy-development.md) | 30-90 min | Build strategy from context to execution | +| [Opportunity Mapping Pipeline](opportunity-mapping-pipeline.md) | 20-60 min | Select one target opportunity from research | +| [Meeting Prep and Recap](meeting-prep-and-recap.md) | 10-30 min | Prepare for and summarize high-stakes meetings | +| [Stakeholder Politics Copilot](stakeholder-politics-copilot.md) | 20-45 min | Review political risk and comms plans | + +## Quick Reference: Common Prompts + +**Daily** +- "What should I work on today?" +- "What's my most important task right now?" + +**Tasks** +- "Clear my backlog" / "Process my backlog" +- "Mark [task] as done" +- "I'm blocked on [task] because [reason]" + +**Planning** +- "Show my P0 and P1 tasks" +- "Show tasks for goal [goal name]" +- "List blocked tasks" / "What's blocked?" +- "Help me plan next week" +- "Run research to feature pipeline" +- "Run decision quality pipeline" +- "Run stakeholder politics copilot" + +**Review** +- "Weekly review" +- "What did I accomplish this week?" +- "How am I tracking against my goals?" + +**Wrap up** +- "Archive completed tasks" +- "Create an eval for this session" diff --git a/examples/uj-1-node-monorepo/Workflows/assumption-validation-pipeline.md b/examples/uj-1-node-monorepo/Workflows/assumption-validation-pipeline.md new file mode 100644 index 0000000..84c9ce8 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/assumption-validation-pipeline.md @@ -0,0 +1,26 @@ +# Assumption Validation Pipeline + +Identify what you are betting on and test the riskiest assumptions first. + +## When to Use + +Use before committing major roadmap or strategy bets. + +## Steps + +1. Map assumptions +- Skill: `assumption-mapping` + +2. Prioritize by risk +- Skill: `assumption-prioritization` + +3. Select fast signals +- Skill: `signal-identification` + +4. Design tests +- Skill: `experiment-design` + +## Exit Criteria + +- Top assumptions have explicit risk scores. +- Chosen tests have success/failure thresholds. diff --git a/examples/uj-1-node-monorepo/Workflows/backlog-processing.md b/examples/uj-1-node-monorepo/Workflows/backlog-processing.md new file mode 100644 index 0000000..43c80e6 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/backlog-processing.md @@ -0,0 +1,91 @@ +# Backlog Processing Workflow + +Turn messy brain dumps into organized, prioritized tasks. + +## When to Use + +- End of day: Process notes captured throughout the day +- Weekly: Clear out accumulated ideas +- After meetings: Turn action items into tasks + +## The Prompt + +``` +Process my backlog +``` + +## Example: Before & After + +### Your BACKLOG.md (messy input) + +```markdown +# Backlog + +- need to follow up with james about the api thing +- Q2 planning thoughts - should we focus on mobile or web first? need to think through this +- bug: users can't upload files larger than 10mb, sarah mentioned this +- write SDK integration patterns doc +- competitor launched new feature, should analyze +- 1:1 with mike tomorrow, prep questions +- expense report overdue +- idea: what if we added AI to the search? +``` + +### The Conversation + +**You:** Process my backlog + +**Claude:** I found 8 items in your backlog. Let me analyze them: + +**Ready to create (5 items):** +| Item | Category | Suggested Priority | +|------|----------|-------------------| +| Follow up with James about API | outreach | P1 | +| Write SDK integration patterns doc | writing | P2 | +| Analyze competitor's new feature | research | P2 | +| Prep questions for Mike 1:1 | admin | P1 (tomorrow) | +| Submit expense report | admin | P1 (overdue) | + +**Needs clarification (2 items):** + +1. "Q2 planning - mobile vs web focus" + - Is this a decision you need to make, or research to inform the decision? + - Should this be a task or added to GOALS.md as a strategic question? + +2. "Bug: file upload > 10mb" + - Is this for you to fix, or should it be tracked in your bug tracker? + - What priority - is it blocking users? + +**Potential duplicate (1 item):** +- "AI search idea" - You have an existing task "Explore AI features for Q2" (68% similar). Should I merge this as a sub-item? + +How would you like me to proceed? + +**You:** The Q2 planning is research I need to do. Bug is P0, users are complaining. Merge the AI idea. + +**Claude:** Got it. Creating 6 tasks: + +✓ Created: Follow up with James about API.md (P1, outreach) +✓ Created: Write SDK integration patterns.md (P2, writing) +✓ Created: Analyze competitor new feature.md (P2, research) +✓ Created: Prep for Mike 1:1.md (P1, admin) +✓ Created: Submit expense report.md (P1, admin) +✓ Created: Research Q2 focus - mobile vs web.md (P2, research) +✓ Created: Fix file upload 10mb limit.md (P0, technical) +✓ Updated: Explore AI features for Q2.md - added search idea + +Backlog cleared. You now have 3 P0/P1 tasks due soon: +1. Fix file upload limit (P0) +2. Expense report (P1, overdue) +3. Mike 1:1 prep (P1, tomorrow) + +Want to start on any of these? + +--- + +## Tips + +- Dump everything into BACKLOG.md throughout the day - don't organize, just capture +- Process at least once per day to keep it manageable +- Be specific when clarifying - Claude will create better tasks +- Review the created tasks briefly to catch any misunderstandings diff --git a/examples/uj-1-node-monorepo/Workflows/core-strategy-development.md b/examples/uj-1-node-monorepo/Workflows/core-strategy-development.md new file mode 100644 index 0000000..3ca6108 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/core-strategy-development.md @@ -0,0 +1,29 @@ +# Core Strategy Development + +Develop strategy from context to execution with explicit tradeoffs. + +## When to Use + +Use when defining or revising product strategy. + +## Steps + +1. Diagnose strategic crux +- Skill: `crux-diagnosis` + +2. Evaluate competitor posture +- Skill: `competitor-analysis` + +3. Draft structured strategy +- Skill: `structured-product-strategy` + +4. Model limit-based trajectory +- Skill: `limit-based-strategy` + +5. Map value chain and vulnerabilities +- Skill: `value-chain-mapping` + +## Exit Criteria + +- Strategy includes objective, pillars, roadmap direction, and assumptions. +- Value chain vulnerabilities and defensive levers are explicit. diff --git a/examples/uj-1-node-monorepo/Workflows/daily-standup.md b/examples/uj-1-node-monorepo/Workflows/daily-standup.md new file mode 100644 index 0000000..d35f3da --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/daily-standup.md @@ -0,0 +1,61 @@ +# Daily Standup Workflow + +A quick 2-minute check-in to set your focus for the day. + +## The Prompt + +``` +What should I work on today? +``` + +## Example Conversation + +**You:** What should I work on today? + +**Claude:** Based on your current tasks and goals, here are your top 3 priorities for today: + +**1. [P0] Finalize Q1 roadmap presentation** (estimated: 90 min) +- Due tomorrow for leadership review +- Aligns with your quarterly objective: "Ship Q1 roadmap" + +**2. [P1] Reply to Sarah's partnership email** (estimated: 20 min) +- Been waiting 3 days, relationship maintenance +- Quick win before deep work + +**3. [P1] Write user story for checkout flow** (estimated: 60 min) +- Blocking engineering from starting sprint work +- Supports goal: "Improve activation by 20%" + +You have 2 blocked tasks I noticed: +- "API integration spec" - waiting on engineering estimates +- "User research synthesis" - waiting on interview transcripts + +Want me to help you get started on any of these? + +--- + +## Variations + +### When You're Overwhelmed + +``` +I'm overwhelmed. What's the ONE thing I should focus on? +``` + +### When You Have Limited Time + +``` +I only have 2 hours before meetings. What can I realistically finish? +``` + +### When You Need Context + +``` +Remind me what I was working on yesterday and what's next. +``` + +## Tips + +- Do this first thing, before checking email/Slack +- Keep it under 2 minutes - just pick and start +- If you're stuck deciding, ask Claude to pick for you diff --git a/examples/uj-1-node-monorepo/Workflows/decision-quality-pipeline.md b/examples/uj-1-node-monorepo/Workflows/decision-quality-pipeline.md new file mode 100644 index 0000000..0f3abd2 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/decision-quality-pipeline.md @@ -0,0 +1,31 @@ +# Decision Quality Pipeline + +Convert ambiguous decisions into auditable, reversible, and role-clear choices. + +## When to Use + +Use when a decision has multiple stakeholders or high impact. + +## Steps + +1. Find root causes and downstream consequences +- Skill: `root-cause-analysis` + +2. Classify reversibility +- Skill: `decision-reversibility` + +3. Structure options cleanly +- Skill: `mece-analysis` +- Skill: `problem-structuring` + +4. Assign decision rights +- Skill: `davci` + +5. Record the decision +- Skill: `decision-journal` + +## Exit Criteria + +- One decider is named. +- Reversibility class is explicit. +- Decision and assumptions are recorded for review. diff --git a/examples/uj-1-node-monorepo/Workflows/meeting-prep-and-recap.md b/examples/uj-1-node-monorepo/Workflows/meeting-prep-and-recap.md new file mode 100644 index 0000000..1449d13 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/meeting-prep-and-recap.md @@ -0,0 +1,29 @@ +# Meeting Prep And Recap + +Prepare for politically complex meetings and capture outputs consistently. + +## When to Use + +Use before and after high-stakes meetings. + +## Steps + +1. Identify hidden agendas +- Skill: `hidden-agendas` + +2. Build influence options +- Skill: `influence-strategies` + +3. Map meeting-specific dynamics +- Skill: `meeting-power-dynamics` + +4. Prepare difficult conversation script (if needed) +- Skill: `difficult-conversations` + +5. Summarize outcomes +- Skill: `ideas-summary` + +## Exit Criteria + +- Stakeholder dynamics are mapped before meeting. +- Decisions, engagements, and actions are captured after meeting. diff --git a/examples/uj-1-node-monorepo/Workflows/opportunity-mapping-pipeline.md b/examples/uj-1-node-monorepo/Workflows/opportunity-mapping-pipeline.md new file mode 100644 index 0000000..19254b9 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/opportunity-mapping-pipeline.md @@ -0,0 +1,23 @@ +# Opportunity Mapping Pipeline + +Move from research evidence to a single target opportunity decision. + +## When to Use + +Use during continuous discovery and prioritization. + +## Steps + +1. Intake and normalize inputs +- Skill: `ost-intake` + +2. Build opportunity tree +- Skill: `opportunity-solution-tree` + +3. Select one target opportunity +- Skill: `ost-target-selection` + +## Exit Criteria + +- Selected opportunity is small, distinct, and moment-scoped. +- Recommendation is traceable to interview evidence. diff --git a/examples/uj-1-node-monorepo/Workflows/research-to-feature-pipeline.md b/examples/uj-1-node-monorepo/Workflows/research-to-feature-pipeline.md new file mode 100644 index 0000000..c6f8eb2 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/research-to-feature-pipeline.md @@ -0,0 +1,34 @@ +# Research To Feature Pipeline + +Transform interview material into testable product moves. + +## When to Use + +Use when you have customer interviews and need a validated path to feature decisions. + +## Steps + +1. Clean transcript +- Skill: `interview-cleanup` +- Output: readable transcript with speaker labels preserved. + +2. Extract JTBD forces +- Skill: `jtbd-extraction` +- Output: pushes, pulls, habits, anxieties grounded in quotes. + +3. Cluster forces across interviews +- Skill: `jtbd-clustering` +- Output: recurring force patterns and unique outliers. + +4. Draft product hypothesis +- Skill: `hypothesis-design` +- Output: one testable hypothesis with measurable outcome. + +5. Design experiment +- Skill: `experiment-design` +- Output: variables, controls, success thresholds, and timeline. + +## Exit Criteria + +- Hypothesis includes action, users, condition, and measurable outcome. +- Experiment includes clear decision rule and confounder controls. diff --git a/examples/uj-1-node-monorepo/Workflows/stakeholder-politics-copilot.md b/examples/uj-1-node-monorepo/Workflows/stakeholder-politics-copilot.md new file mode 100644 index 0000000..22c8269 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/stakeholder-politics-copilot.md @@ -0,0 +1,29 @@ +# Stakeholder Politics Copilot + +Reduce political risk and improve adoption for feature and strategy proposals. + +## When to Use + +Use before circulating PRDs, updates, or strategy memos. + +## Steps + +1. Build baseline stakeholder map +- Skill: `power-map` + +2. Review stakeholder risks for proposal +- Skill: `stakeholder-risk-review` + +3. Create audience-specific framing +- Skill: `message-framing-comms` + +4. Review executive update quality +- Skill: `executive-update-review` + +5. Generate challenge questions for prep +- Skill: `challenging-stakeholder-questions` + +## Exit Criteria + +- Risks have mitigations and owners. +- Comms plan includes sequence, CTA, and measurable signals. diff --git a/examples/uj-1-node-monorepo/Workflows/weekly-review.md b/examples/uj-1-node-monorepo/Workflows/weekly-review.md new file mode 100644 index 0000000..9c98150 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/weekly-review.md @@ -0,0 +1,129 @@ +# Weekly Review Workflow + +A 15-30 minute session to reflect on progress and plan ahead. + +## When to Do It + +- Friday afternoon (reflect) +- Sunday evening (prep) +- Monday morning (plan) + +## The Prompts + +### Step 1: Review Completed Work + +``` +What did I accomplish this week? +``` + +**Example response:** + +This week you completed 12 tasks: + +**By Goal Alignment:** +- "Ship Q1 roadmap": 4 tasks (roadmap presentation, 2 specs, stakeholder review) +- "Improve activation": 2 tasks (checkout flow analysis, user interviews) +- "Build SDK expertise": 1 task (integration guide published) +- Maintenance/admin: 5 tasks + +**Highlights:** +- Finished Q1 roadmap presentation (P0) - major milestone +- Published your first SDK integration guide +- Cleared 5 admin tasks that were piling up + +**Time invested:** ~18 hours of focused work logged + +--- + +### Step 2: Check Goal Progress + +``` +How am I tracking against my quarterly goals? +``` + +**Example response:** + +**Q1 Goals Progress (Week 3 of 12):** + +| Goal | Status | Notes | +|------|--------|-------| +| Ship Q1 roadmap | 🟢 On track | Presentation done, specs 60% complete | +| Improve activation by 20% | 🟡 Needs attention | Research done, no implementation started | +| Build thought leadership | 🟢 On track | 1 of 4 planned posts published | + +**Recommendations:** +- Activation goal needs more focus next week +- Consider adding a P1 task to kick off checkout improvements + +--- + +### Step 3: Identify Blockers + +``` +What's blocked or stalled? +``` + +**Example response:** + +**Blocked tasks (3):** +1. "API integration spec" - waiting on engineering estimates (5 days) + → Suggest: Follow up with James Monday AM + +2. "User research synthesis" - waiting on transcripts (3 days) + → Suggest: Check with research team + +3. "Mobile prototype review" - waiting on design (7 days) + → Suggest: Escalate to design lead + +**Stalled tasks (started but no progress this week):** +1. "Competitive analysis doc" - started 2 weeks ago, 20% complete + → Is this still a priority? + +--- + +### Step 4: Plan Next Week + +``` +Help me plan next week. What should my top priorities be? +``` + +**Example response:** + +Based on your goals and current tasks, here's a suggested focus: + +**Must do (P0/P1):** +1. Unblock API integration - follow up Monday +2. Start checkout flow implementation planning +3. Write SDK v2 migration guide (due Friday) + +**Should do (P2):** +4. Finish competitive analysis +5. Prep for Thursday's product review + +**If time allows:** +6. Research AI search feature idea +7. Clean up documentation backlog + +**Time budget:** +- Deep work available: ~15 hours +- Meetings: ~10 hours +- Buffer for urgent items: ~5 hours + +Does this feel right, or should we adjust priorities? + +--- + +## Quick Version (5 minutes) + +If you're short on time: + +``` +Quick weekly review: What did I finish, what's blocked, what's most important next week? +``` + +## Tips + +- Block 30 minutes on your calendar for this +- Do it in a quiet space, not between meetings +- Be honest about what's stalled - it's data, not judgment +- Update GOALS.md if priorities have shifted diff --git a/examples/uj-1-node-monorepo/Workflows/wrap-up-protocol.md b/examples/uj-1-node-monorepo/Workflows/wrap-up-protocol.md new file mode 100644 index 0000000..2ec6b99 --- /dev/null +++ b/examples/uj-1-node-monorepo/Workflows/wrap-up-protocol.md @@ -0,0 +1,76 @@ +# Phase Wrap-Up Protocol + +Apply this when completing phases, features, or fixes. Evidence before claims, always. + +## Before Calling Work Complete + +### 1. Run Verification Commands (Show Output) + +- Run tests: show "X/X pass" (not "tests should pass") +- Run linter: show "0 errors" (not "linter looks clean") +- Run build: show "exit 0" (not "build probably works") +- Test manually: follow actual steps, show results + +### 2. Verify Objectives + +- Read requirements/plan line by line +- Check each objective off with evidence +- If any incomplete, state what remains + +### 3. Update Documentation + +- README status section - what works now +- Any testing docs if new features added +- Spec/plan if implementation differed + +### 4. Proactive Completion Signal + +Say explicitly: "Let's wrap up [Phase/Feature X]" + +### 5. Walk Through Testing + +Concrete steps: "Click X, you should see Y" +Not vague: "test the feature" + +### 6. Wait for Confirmation + +Never proceed to next phase without user sign-off. + +### 7. Memory Sweep + +Ask: "What did I learn this session that future sessions need to know?" + +Check: +- [ ] Any gotchas discovered? -> Add to AGENTS.md +- [ ] Any patterns that worked well? -> Add to AGENTS.md +- [ ] Any divergence from spec? -> Update spec with decision + rationale +- [ ] Any new capabilities? -> Update README +- [ ] Any new testing needed? -> Document + +Don't let hard-won knowledge die with this session. + +### 8. Commit Readiness + +- Suggest clear commit message +- Verify all changed files included +- Check no temporary/debug code remains + +## Red Flags - Never Say + +- "Should work now" +- "Tests passed" (without showing output) +- "Phase complete, moving to Phase X" (without confirmation) + +## Scale to Work Size + +- **Big phases**: Full checklist +- **Small tasks**: Abbreviated but still intentional +- **Always**: Verify it works and signal completion clearly + +## Why This Matters + +- Prevents building on broken foundations +- Maintains documentation accuracy +- Creates natural stopping points +- Ensures we can return to working state +- Makes each phase independently valuable diff --git a/examples/uj-1-node-monorepo/skills b/examples/uj-1-node-monorepo/skills new file mode 120000 index 0000000..5018230 --- /dev/null +++ b/examples/uj-1-node-monorepo/skills @@ -0,0 +1 @@ +.agents/skills \ No newline at end of file diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/800-core.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/800-core.mdc new file mode 100644 index 0000000..a74d5c1 --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/800-core.mdc @@ -0,0 +1,10 @@ +--- +description: Core project standards +globs: "**/*.md" +alwaysApply: true +--- +# Core Standards + +- All markdown files use ATX headers (# not ===) +- Dates in YYYY-MM-DD format +- File names in kebab-case diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/801-designs.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/801-designs.mdc new file mode 100644 index 0000000..dad9181 --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/801-designs.mdc @@ -0,0 +1,10 @@ +--- +description: Architecture and design documents +globs: Designs/**/* +alwaysApply: true +--- +# Design Standards + +- Every design doc needs a Status field (Draft, Review, Approved, Deprecated) +- Reference ADRs by ID +- Include Mermaid diagrams for system interactions diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/802-operations.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/802-operations.mdc new file mode 100644 index 0000000..2a3a363 --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/802-operations.mdc @@ -0,0 +1,10 @@ +--- +description: Operations and hiring pipeline +globs: Operations/**/* +alwaysApply: true +--- +# Operations Standards + +- Job descriptions follow template in Operations/templates/ +- Interview notes must reference Job-ID +- Candidate files: candidate_[first]-[last].md diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/803-workitems.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/803-workitems.mdc new file mode 100644 index 0000000..f15d0ec --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/803-workitems.mdc @@ -0,0 +1,10 @@ +--- +description: Team work items and sprint tracking +globs: Team-Workitems/**/* +alwaysApply: true +--- +# Work Item Standards + +- Work items have frontmatter: status, priority, assignee +- Link to design docs via Design-Ref field +- Use [P0]-[P3] priority prefix in filename diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/804-infra.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/804-infra.mdc new file mode 100644 index 0000000..9ebe44e --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/804-infra.mdc @@ -0,0 +1,10 @@ +--- +description: Infrastructure as code standards +globs: Infrastructure/**/* +alwaysApply: true +--- +# Infrastructure Standards + +- Terraform modules follow standard structure (main.tf, variables.tf, outputs.tf) +- All resources tagged with environment and team +- No hardcoded secrets (use variable references) diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/805-placeholder.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/805-placeholder.mdc new file mode 100644 index 0000000..f6f0741 --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/805-placeholder.mdc @@ -0,0 +1,7 @@ +--- +description: Rule 805 placeholder +globs: "**/*.md" +alwaysApply: false +--- +# Rule 805 +Placeholder rule for testing numbering detection. diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/806-placeholder.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/806-placeholder.mdc new file mode 100644 index 0000000..03a66c5 --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/806-placeholder.mdc @@ -0,0 +1,7 @@ +--- +description: Rule 806 placeholder +globs: "**/*.md" +alwaysApply: false +--- +# Rule 806 +Placeholder rule for testing numbering detection. diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/807-placeholder.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/807-placeholder.mdc new file mode 100644 index 0000000..df05346 --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/807-placeholder.mdc @@ -0,0 +1,7 @@ +--- +description: Rule 807 placeholder +globs: "**/*.md" +alwaysApply: false +--- +# Rule 807 +Placeholder rule for testing numbering detection. diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/808-placeholder.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/808-placeholder.mdc new file mode 100644 index 0000000..0d1e2e2 --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/808-placeholder.mdc @@ -0,0 +1,7 @@ +--- +description: Rule 808 placeholder +globs: "**/*.md" +alwaysApply: false +--- +# Rule 808 +Placeholder rule for testing numbering detection. diff --git a/examples/uj-2-architect-monorepo/.cursor/rules/809-placeholder.mdc b/examples/uj-2-architect-monorepo/.cursor/rules/809-placeholder.mdc new file mode 100644 index 0000000..7c7db56 --- /dev/null +++ b/examples/uj-2-architect-monorepo/.cursor/rules/809-placeholder.mdc @@ -0,0 +1,7 @@ +--- +description: Rule 809 placeholder +globs: "**/*.md" +alwaysApply: false +--- +# Rule 809 +Placeholder rule for testing numbering detection. diff --git a/examples/uj-2-architect-monorepo/AGENTS.md b/examples/uj-2-architect-monorepo/AGENTS.md new file mode 100644 index 0000000..520922e --- /dev/null +++ b/examples/uj-2-architect-monorepo/AGENTS.md @@ -0,0 +1,10 @@ +# Team Agents + +## Architect +Responsible for system design decisions, blueprint reviews, and infrastructure planning. + +## Operations Lead +Responsible for hiring pipeline, candidate assessment, and team coordination. + +## Engineering Manager +Responsible for sprint planning, work item decomposition, and delivery tracking. diff --git a/examples/uj-3-flask-simple/.agents/skills/README.md b/examples/uj-3-flask-simple/.agents/skills/README.md new file mode 100644 index 0000000..aa12943 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/README.md @@ -0,0 +1,35 @@ +# Skills (Canonical) + +This directory is the canonical runtime skill location for Codex/OpenAI-style skills. + +## Layout + +- One folder per skill +- Each skill folder must contain `SKILL.md` +- Optional agent-specific metadata can live at `agents/openai.yaml` +- Recommended: include `## When to Use` and `## When Not to Use` sections + +Example: + +``` +.agents/skills/verification/SKILL.md +.agents/skills/verification/agents/openai.yaml +.agents/skills/tdd/SKILL.md +.agents/skills/linear-issue-sync/SKILL.md +``` + +## Source of Truth + +Runtime skill packs in `.agents/skills/` are the source of truth. + +Edit skills directly in this directory, then validate: + +```bash +python scripts/validate_skills.py +``` + +If using Claude-specific skill discovery, this repo bridges: + +```bash +.claude/skills -> ../.agents/skills +``` diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/SKILL.md new file mode 100644 index 0000000..cae9a0b --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/SKILL.md @@ -0,0 +1,380 @@ +# Agentic-OS AI-Assisted Setup + +## Purpose + +Intelligent, complexity-aware setup for agentic-os. Performs two jobs: + +1. **Workspace bootstrapping** — Creates the agentic-os workspace structure (directories, AGENTS.md, GOALS.md, BACKLOG.md, symlinks, skills, workflows) in the target repo, auto-populating GOALS.md from repo analysis instead of a questionnaire. +2. **Configuration generation** — Scans repo structure, classifies complexity, proposes runtime-specific configuration proportional to detected needs, previews as unified diffs, and writes only after approval. + +Both jobs run in sequence. The AI replaces the classic setup questionnaire entirely — it infers what the questionnaire would have asked from the repo's own signals. + +## Mode Detection + +Before beginning, check for the context bridge file at `.agents/.agentic-os-setup-context.json`. If present, read it to determine: +- `runtimes`: which runtime adapters to generate for +- `dry_run`: if true, perform full analysis and proposal but write zero files +- `track`: if true, skip gitignore management (files will be committed) +- `auto`: if true, show the diff preview but skip the approval gate — write immediately after presenting diffs + +Note: By the time you run, `setup.sh` has already bootstrapped the workspace (copied skills, workflows, dirs, BACKLOG.md, symlinks into this repo). Your job is the smart parts: scan, classify, infer GOALS.md, generate runtime config, and handle files that need cross-referencing (CLAUDE.md, AGENTS.md, etc.). + +If the context bridge file is not present, ask the user which runtimes they want and whether this is a dry run. + +Check for an existing manifest at `.agents/.agentic-os-manifest.json`: +- If manifest exists: this is a **re-run**. Phase 1 does not support re-run — inform the user that re-run with delta merging is planned for Phase 2, and suggest `setup.sh --remove` followed by a fresh `--ai` run if they want to regenerate. +- If no manifest: this is a **first-run**. Proceed with workspace bootstrapping, then scanning. + +## AI Responsibilities (Post-Bootstrap) + +`setup.sh` has already handled the "dumb" copying: directories, BACKLOG.md, Workflows/, .agents/skills/, symlinks, .gitignore template. Your job is the smart inference and generation: + +### 1. Create or update AGENTS.md + +If `AGENTS.md` does NOT exist: copy the standard agentic-os AGENTS.md from `.agents/skills/agentic-os-setup/` reference (the AI should generate a fresh AGENTS.md following the agentic-os template structure — workspace layout, task format, categories, priority levels, backlog processing, daily guidance, skills reference, workflows reference). + +If `AGENTS.md` already exists: extend it with a managed block containing agentic-os behavioral rules (scope isolation, cross-references, etc.) — same as Antigravity adapter behavior. + +### 2. Create or update AI tool wrapper files + +For each targeted runtime, create the appropriate wrapper file if it doesn't exist: +- **Claude**: `CLAUDE.md` — if missing, create with `@AGENTS.md`. If exists, create `CLAUDE-agentic-os.md` companion. +- **Codex**: `CODEX.md` — if missing, create with reference to AGENTS.md + skill location. +- **Pi**: `PI.md` — if missing, create with reference to AGENTS.md + skill location. +- **OpenClaw**: `OPENCLAW.md` — if missing, create with reference to AGENTS.md + skill location. + +### 3. Auto-generate GOALS.md + +Instead of asking a questionnaire, infer goals from repo signals: + +| Classic Question | AI Inference Source | +|-----------------|-------------------| +| "What's your current role?" | README, CONTRIBUTING, package.json author, git config, folder structure purpose | +| "What's your professional vision?" | Repo scope: what domain it serves, what it's building toward | +| "12-month success criteria?" | Open issues, roadmap files, TODO/BACKLOG, README goals section | +| "This quarter objectives?" | Recent commits focus, active branches, work-in-progress indicators | +| "Top 3 priorities?" | Most-edited directories, recent activity, README priority sections | + +Write `GOALS.md` using the standard template structure. Mark inferred sections with `[AI-inferred — refine as needed]`. Leave unknowable fields empty with ``. + +### 4. Generate runtime-specific configuration + +This is the classification + proposal flow (Scanning → Classification → Proposal → Preview → Write) described in the sections below. + +--- + +## Scanning Protocol + +### What to Read + +Scan the repository filesystem for structural signals: + +1. **Top-level directories** — list all directories at root (ignore hidden dirs except `.cursor/`, `.claude/`, `.cline/`) +2. **Config files at root** — package.json, pyproject.toml, Cargo.toml, go.mod, Makefile, docker-compose.yml, terraform/, .github/ +3. **Existing AI configuration** — .cursor/rules/*.mdc, CLAUDE.md, .clinerules, AGENTS.md, .claude/ +4. **Agent frameworks** — _bmad/, .agents/ contents +5. **Documentation** — docs/, README.md, CONTRIBUTING.md +6. **Team indicators** — directories containing "team", group-based folder structures + +### What NOT to Read + +- File contents beyond config/manifest files (respect privacy — NFR-5) +- Binary files +- node_modules/, .git/, build artifacts, vendor/ +- Any file > 100KB + +### Signal Matching + +Cross-reference detected patterns against `catalog.md`. For each matched signal, note: +- Which complexity dimension it contributes to +- What setup implications it carries +- Any coexistence behavior required + +## Classification Logic + +Use the **highest-dimension-wins** scoring algorithm: + +### Dimensions + +| Dimension | Zero | Simple | Multi | Complex | +|-----------|------|--------|-------|---------| +| Top-level concern folders | 0 | 1-2 | 3-4 | 5+ | +| Existing AI config files | 0 | 0-1 | 2-3 | 4+ | +| Team/group indicators | 0 | 0 | 1 | 2+ | +| Cross-domain references detected | 0 | 0 | 1 | 2+ | +| Agent framework present (_bmad/, etc.) | No | No | No | Yes | + +### Algorithm + +1. For each dimension, map the detected count to a tier (Zero=0, Simple=1, Multi=2, Complex=3) +2. Take the maximum score across all dimensions +3. If max = 0 → **Zero** tier; 1 → **Simple**; 2 → **Multi**; 3 → **Complex** +4. Present the classification WITH the scoring breakdown so the user can challenge it + +### Override Protocol + +Always propose the classification with rationale. The user can override up or down. Respect the override without argument. + +### Calibration + +- A repo with `_bmad/` is automatically Complex (framework presence is a strong signal) +- A repo with only `src/` and `tests/` should never exceed Simple regardless of file count +- See `examples/simple-output.md` and `examples/complex-output.md` for calibration + +## Proposal Generation + +Based on the classified tier and detected signals, assemble a configuration proposal: + +### Tier Output Expectations + +| Tier | What Gets Generated | +|------|-------------------| +| Zero | Nothing — repo is empty. Suggest running classic `setup.sh` instead. | +| Simple | 1 config file per targeted runtime. Minimal: basic project context, no persona routing. | +| Multi | Config files per runtime + AGENTS.md with persona definitions. Persona routing, scope isolation. | +| Complex | Full output: AGENTS.md, GOALS.md (if none exists), config files with persona routing, scope isolation, cross-reference enforcement, quality gates. | + +### Assembly Process + +1. Select applicable templates from `templates/` based on tier and detected signals (check each template's "When to Use" section) +2. Fill template placeholders with detected values (domains, personas, relationships) +3. Format output per runtime using the corresponding adapter in `adapters/` +4. Collect all proposed files into a unified proposal + +### Relationship Discovery + +- **Manifest-declared relationships** (found in package.json workspaces, go.work, etc.) are trusted — include them directly +- **AI-inferred relationships** (e.g., folder naming patterns suggest linkage) require user confirmation before inclusion in generated rules + +## Framework Coexistence + +When `_bmad/` directory is detected during scanning: +- Do NOT generate persona routing rules (defer persona ownership to BMAD) +- Limit generated rules to: scope isolation, cross-reference enforcement, naming patterns +- Explain what you're deferring and why in the proposal + +When other AI configs exist (.cursor/rules/, CLAUDE.md, .clinerules): +- Do NOT modify or replace them +- Generate agentic-os rules as additive companion files (see adapter specs for pre-existing file behavior) +- Check for glob collisions with existing .cursor/rules/ before proposing new ones + +## Diff Preview Protocol + +All proposed changes MUST be presented as unified diffs before any files are written. + +### New Files + +Present as a diff against `/dev/null`: + +```diff +--- /dev/null ++++ b/CLAUDE.md +@@ -0,0 +1,25 @@ ++# Project Context ++ ++{full file content with + prefix on each line} +``` + +### Extensions to Existing Files + +For files being extended (e.g., AGENTS.md managed block append, .gitignore append): + +```diff +--- a/.gitignore ++++ b/.gitignore +@@ -42,0 +43,5 @@ ++# === AGENTIC-OS GENERATED (do not edit this block) === ++CLAUDE.md ++.agents/.agentic-os-manifest.json ++# === END AGENTIC-OS GENERATED === +``` + +### Presentation Rules + +1. Show ALL proposed files in a single diff block (or clearly labeled separate blocks) +2. Use standard unified diff format compatible with `patch` and `git apply` +3. Include file paths relative to repo root +4. For multi-file proposals, separate each file's diff with a blank line +5. After presenting diffs, clearly state: "These are the proposed changes. Approve all, approve selectively, or reject?" + +### Selective Approval + +The user can: +- **Approve all** — write everything as proposed +- **Approve selectively** — specify which files to write (e.g., "write CLAUDE.md and the manifest but skip the Cursor rules") +- **Reject** — write nothing, end the session + +Respect the user's selection exactly. Only write approved files. + +### Auto-Approval Mode + +When `auto: true` is set in the context bridge: + +1. Present all diffs exactly as in normal mode (for logging/audit) +2. **Do NOT wait for user approval** — proceed directly to writing +3. If conflict detection finds a collision: **FAIL with error** (do not silently overwrite). Print the conflict report and exit without writing any files. +4. If `dry_run` is also true: show diffs, write nothing (dry-run takes precedence over auto) + +Auto mode is designed for unattended execution where the user has pre-selected their runtimes via `--runtime`. It still shows what will be written but doesn't pause for confirmation. + +## Dry-Run Mode + +When dry-run is active (detected from context bridge `dry_run: true` or user states "dry run"): + +1. Execute the FULL workflow: scanning, classification, proposal generation +2. Present diffs exactly as in normal mode +3. **Write ZERO files to disk** +4. Do NOT create a manifest +5. Do NOT modify .gitignore +6. Clearly indicate at the start and end: "DRY RUN — no files will be written" + +The user gets full visibility into what WOULD happen, without any side effects. + +## Conflict Detection Protocol + +Before writing ANY file, perform these safety checks: + +### Cursor Glob Collision Detection + +When proposing `.cursor/rules/` files: + +1. List ALL existing `.mdc` files in `.cursor/rules/` +2. Parse YAML frontmatter of each to extract `globs` value +3. Compare each proposed glob against all existing globs +4. A collision exists if: + - Proposed glob is identical to an existing glob + - Proposed glob is a superset of an existing glob (e.g., `src/**/*` covers `src/components/**/*`) + - Proposed glob overlaps with an existing glob (shared file matches) + +**On collision:** +- Report: existing file name, its glob, proposed glob, and why they conflict +- Propose alternatives: narrower glob that avoids overlap, or skip that rule +- Never write a colliding rule without user approval of the alternative + +### Numbering Respect + +When generating Cursor `.mdc` files: +1. Scan existing files for their numeric prefixes +2. Identify the highest number in use +3. Use the next available number (e.g., if 805 exists, use 806) +4. NEVER renumber or move existing files +5. If no existing rules, default to 900-band + +### Non-Destructive File Policy + +**Core invariant:** Never modify or delete user files. + +**Exceptions (append-only managed blocks):** +- `.gitignore` — append a delimited block at the end (never edit existing lines) +- `AGENTS.md` — append a managed block at the end (never edit existing content above the block) + +**For all other existing files:** +- If the target path already exists and is NOT one of the append-only exceptions: create a companion file instead (see adapter specs for per-runtime behavior) +- If an existing managed block has been edited by the user (hash mismatch): warn and skip overwrite + +### Framework Coexistence Check + +When `_bmad/` is detected: +- Skip persona routing template entirely +- Explain in the proposal: "Persona routing deferred to BMAD framework (detected `_bmad/` directory)" +- Only generate: scope isolation, cross-reference enforcement, naming, quality gates + +## Write Protocol + +After the user approves the proposal (fully or selectively), write files following this exact sequence: + +### Write Sequence + +1. Create approved configuration files (CLAUDE.md, .cursor/rules/*.mdc, .clinerules, AGENTS.md extension) +2. Write the manifest (`.agents/.agentic-os-manifest.json`) +3. Update .gitignore (unless `--track` was specified) + +### Manifest Schema + +Write to `.agents/.agentic-os-manifest.json`: + +```json +{ + "version": "1.0.0", + "created_at": "", + "complexity_tier": "", + "runtimes_targeted": ["", ""], + "files": [ + { + "path": "", + "created_at": "", + "content_hash": "sha256:" + } + ], + "denied_relationships": [], + "detected_frameworks": [""] +} +``` + +**Field definitions:** +- `version` — Schema version (always "1.0.0" for Phase 1). Future phases add fields but never remove or rename existing ones (additive-only evolution). +- `created_at` — When the setup was run +- `complexity_tier` — The classified tier +- `runtimes_targeted` — Which runtimes were configured +- `files` — Every file created or modified by this run. Each entry has the file path, creation timestamp, and SHA-256 hash of content. +- `denied_relationships` — Relationships the user rejected during proposal (prevents re-proposal on future re-runs) +- `detected_frameworks` — Frameworks found during scanning (e.g., "bmad") + +**Important:** The manifest must include ALL generated files — this is what `setup.sh --remove` uses for clean uninstall. Missing entries = orphaned files on removal. + +### Gitignore Management + +**Default behavior** (when `--track` was NOT specified): + +Append a managed block at the end of `.gitignore`: + +```gitignore +# === AGENTIC-OS GENERATED (do not edit this block) === + +.agents/.agentic-os-manifest.json +# === END AGENTIC-OS GENERATED === +``` + +Rules: +- List every file path from the manifest's `files` array +- Include the manifest itself +- Always append at the end — never insert or modify existing gitignore content +- If `.gitignore` doesn't exist, create it with just the managed block +- The context bridge file (`.agents/.agentic-os-setup-context.json`) is NOT gitignored — it's ephemeral and deleted by `--remove` + +**When `--track` is specified:** +- Do NOT modify `.gitignore` +- Generated files will be committed to the repository +- This is intentional — the user wants the configuration shared with their team + +### Managed Block Specification + +For files that use managed blocks (AGENTS.md, .gitignore): + +**HTML-comment style** (for AGENTS.md and other markdown files): +``` + +{content} + +``` + +**Comment style** (for .gitignore and other non-markdown files): +``` +# === AGENTIC-OS GENERATED (do not edit this block) === +{content} +# === END AGENTIC-OS GENERATED === +``` + +**Hash computation:** +- Hash the content BETWEEN the markers (not including markers themselves) +- Use SHA-256 +- Store as hex string in the start marker +- Purpose: Phase 2 re-run can detect if user manually edited managed content + +### Post-Write Confirmation + +After writing all approved files: +1. Print a summary of what was written (file paths and sizes) +2. Confirm the manifest was created +3. Confirm gitignore status (updated or skipped due to --track) +4. Remind user: "To undo, run: setup.sh --remove" diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/antigravity.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/antigravity.md new file mode 100644 index 0000000..408abfc --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/antigravity.md @@ -0,0 +1,148 @@ +# Adapter: Antigravity + +## Purpose + +Describes how to format agentic-os generated output for Antigravity AI consumption via AGENTS.md. + +## File Path Convention + +- **Primary:** `AGENTS.md` at repo root +- **Behavior:** Always EXTEND existing content — never replace + +## Format Specification + +Antigravity reads AGENTS.md as its primary instruction file. It expects structured markdown with: + +- `##` headers for major sections (Personas, Rules, Standards) +- `###` headers for subsections (individual personas, rule groups) +- Tables for structured data (scope boundaries, relationships) +- Bullet lists for behavioral rules +- Imperative tone ("Focus on X", "Validate Y", "Never Z") + +## Constraints + +- Single file (AGENTS.md) +- Must coexist with user-written content +- Agentic-os content lives ONLY within managed block markers +- User content above the managed block is never touched +- If no AGENTS.md exists, create one entirely within managed markers + +## Managed Block Format + +```markdown + +{generated content goes here} + +``` + +- **Start marker:** `` +- **End marker:** `` +- **Hash:** SHA-256 of the content between markers (enables future re-run detection) +- **Placement:** Always at the END of AGENTS.md (below any user content) + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No AGENTS.md exists | Create AGENTS.md with content entirely within managed block | +| AGENTS.md exists without managed block | Append managed block at end of file | +| AGENTS.md exists with managed block | Replace managed block content (preserve everything outside) | +| User edited content inside managed block | Detect hash mismatch → warn user and skip overwrite | + +## Extend Semantics + +``` +AGENTS.md structure: +┌─────────────────────────────────────────────────────────────────┐ +│ [User's original content] │ ← never touched +│ ... │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ## Agentic-OS Generated Rules │ +│ {all generated content here} │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Examples + +### Example 1: New AGENTS.md (no existing file) + +```markdown + +## Agentic-OS Generated Rules + +### Project Context + +This is a Go microservices project with 3 services. + +### Quality Gates + +- Run `go test ./...` before completing work +- Run `golangci-lint run` for code quality +- Ensure new packages have corresponding test files + + +``` + +### Example 2: Extending existing AGENTS.md (Complex tier) + +User's existing content (preserved as-is): +```markdown +# Team Agents + +## Product Manager +Responsible for roadmap decisions... + +## Tech Lead +Responsible for architecture decisions... +``` + +After agentic-os extension: +```markdown +# Team Agents + +## Product Manager +Responsible for roadmap decisions... + +## Tech Lead +Responsible for architecture decisions... + + +## Agentic-OS Generated Rules + +### Personas + +#### Architect +**Scope:** `/Designs/` +**Focus:** System design, scalability, requirements traceability +**Behavioral rules:** +- Prioritize structural patterns over quick fixes +- Reference existing blueprints before proposing new structures + +#### Operations Specialist +**Scope:** `/Operations/` +**Focus:** Process efficiency, documentation completeness +**Behavioral rules:** +- Follow documentation standards +- Enforce cross-reference rules + +### Scope Boundaries + +| Domain | Isolated From | Rationale | +|--------|--------------|-----------| +| Designs/ | Operations/ | Architecture and HR are independent | +| Operations/ | Designs/ | Recruitment is independent of design | + +### Cross-References + +| Source | Target | Link Format | +|--------|--------|-------------| +| Operations/interviews/ | Operations/job-descriptions/ | `Job-ID: jd-*` | + + +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Antigravity as a runtime. It formats the assembled proposal (from templates) into AGENTS.md content within managed block markers, preserving any existing user content above the block. diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/claude.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/claude.md new file mode 100644 index 0000000..da09b94 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/claude.md @@ -0,0 +1,86 @@ +# Adapter: Claude Code + +## Purpose + +Describes how to format agentic-os generated output for Claude Code consumption. + +## File Path Convention + +- **Primary:** `CLAUDE.md` at repo root +- **If CLAUDE.md already exists:** Create `CLAUDE-agentic-os.md` as a companion file. Never modify the existing CLAUDE.md. + +## Format Specification + +Claude Code reads CLAUDE.md as a markdown file with freeform structure. Effective patterns: + +- Use `##` headers to organize sections (Persona Routing, Scope Isolation, Quality Gates, etc.) +- Bullet lists for rules and constraints +- Code blocks for commands and patterns +- Keep instructions direct and imperative ("Do X", "Never Y") + +## Constraints + +- Single file (no directory structure like Cursor) +- No frontmatter or metadata — pure markdown +- No glob-based routing — all rules apply globally (Claude Code doesn't have file-scoped rules) +- Rules must be self-describing (include "when editing in X" context inline) + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No CLAUDE.md exists | Create `CLAUDE.md` | +| CLAUDE.md exists | Create `CLAUDE-agentic-os.md` as companion. Add a note at top: "This file supplements the existing CLAUDE.md with agentic-os configuration." | + +Never modify an existing CLAUDE.md. + +## Examples + +### Example 1: Simple Tier (single-purpose project) + +```markdown +# Project Context + +This is a Python FastAPI project using pytest for testing. + +## Quality Gates + +Before completing work: +- Run tests: `pytest` +- Run type checking: `mypy src/` +- Run formatting: `ruff format --check .` + +## Project Structure + +- `src/` — Application source (FastAPI routes and models) +- `tests/` — Test files (pytest) +- `alembic/` — Database migrations +``` + +### Example 2: Multi Tier (multiple concerns) + +```markdown +# Agentic-OS Configuration + +## Persona Routing + +- **Backend Mode:** Triggered when editing `/backend/`. Focus on API design, data modeling, and performance. +- **Frontend Mode:** Triggered when editing `/frontend/`. Focus on component architecture, accessibility, and UX. +- **DevOps Mode:** Triggered when editing `/infra/`. Focus on reliability, security, and cost optimization. + +## Scope Isolation + +Do not cross-reference between isolated domains unless explicitly asked: +- `/backend/` and `/frontend/` have distinct conventions +- `/infra/` is independent from application code + +## Quality Gates + +- Backend: `cd backend && pytest && mypy .` +- Frontend: `cd frontend && npm test && npm run lint` +- Infrastructure: `cd infra && terraform validate` +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Claude Code as a runtime. It formats the assembled proposal (from templates) into Claude-appropriate markdown, respecting the constraints above. diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/cline.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/cline.md new file mode 100644 index 0000000..8ea84b8 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/cline.md @@ -0,0 +1,85 @@ +# Adapter: Cline + +## Purpose + +Describes how to format agentic-os generated output for Cline AI consumption. + +## File Path Convention + +- **Primary:** `.clinerules` at repo root +- **If `.clinerules` already exists:** Create `.clinerules-agentic-os` as a companion file. Never modify the existing `.clinerules`. + +## Format Specification + +Cline reads `.clinerules` as a plain text/markdown file containing behavioral instructions. Effective patterns: + +- Use `##` headers to organize sections +- Direct imperative rules ("Always X", "Never Y", "When doing Z, ensure W") +- Bullet lists for grouped rules +- Keep language concise and actionable + +## Constraints + +- Single file (no directory-based rule system like Cursor) +- No frontmatter or metadata +- No glob-based routing — all rules apply globally +- Rules must be self-describing (include path context inline where needed) +- Simpler format than Claude or Cursor — focus on behavioral directives + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No `.clinerules` exists | Create `.clinerules` | +| `.clinerules` exists | Create `.clinerules-agentic-os` as companion. Never modify existing file. | + +## Examples + +### Example 1: Simple Tier + +```markdown +# Project Rules + +## Quality Gates + +- Always run `npm test` before completing work +- Always run `npm run lint` before completing work +- New source files must have corresponding test files + +## Project Structure + +- Source code lives in `src/` +- Tests live in `tests/` +- Follow existing naming conventions +``` + +### Example 2: Multi Tier + +```markdown +# Agentic-OS Rules + +## Persona Routing + +When working in `/backend/`: +- Focus on API design, data modeling, and performance +- Follow Python conventions (PEP 8, type hints) + +When working in `/frontend/`: +- Focus on component architecture and accessibility +- Follow React/TypeScript conventions + +## Scope Isolation + +- Do not suggest content from `/backend/` when working in `/frontend/` +- Do not suggest content from `/frontend/` when working in `/backend/` +- Keep suggestions scoped to the current domain + +## Quality Gates + +- Backend: run `pytest` and `mypy` before completing work +- Frontend: run `npm test` and `npm run lint` before completing work +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Cline as a runtime. It formats the assembled proposal (from templates) into Cline-appropriate rules, respecting the single-file, directive-focused format. diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/cursor.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/cursor.md new file mode 100644 index 0000000..594925c --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/adapters/cursor.md @@ -0,0 +1,138 @@ +# Adapter: Cursor + +## Purpose + +Describes how to format agentic-os generated output for Cursor AI consumption via `.cursor/rules/` files. + +## File Path Convention + +- **Directory:** `.cursor/rules/` +- **Filename:** `NNN-agentic-os.mdc` or `NNN-agentic-os-{concern}.mdc` +- **Numbering:** Use the next available number in the appropriate band. Default to 900-band if no convention exists. If existing rules use a different band, append after the highest existing number. + +### Numbering Detection + +1. List all existing `.mdc` files in `.cursor/rules/` +2. Extract the numeric prefix from each filename +3. Identify the convention (e.g., 0XX=core, 1XX=tools, 8XX=workflow) +4. Place agentic-os rules in the highest available band (typically 900+) +5. Never renumber or move existing files + +## Format Specification + +Each `.mdc` file requires YAML frontmatter: + +```yaml +--- +description: Human-readable description of this rule's purpose +globs: path/to/files/**/*.ext +alwaysApply: true +--- +``` + +**Required fields:** +- `description` — Clear, concise explanation (shown in Cursor's rule list) +- `globs` — File patterns this rule applies to + +**Optional fields:** +- `alwaysApply` — Set to `true` when the rule should always be active for matched files + +**Body:** Markdown content after frontmatter contains the actual rules. + +## Constraints + +- Each file targets specific globs — rules are file-scoped, not global +- Globs must be specific: NEVER use `*` alone (too broad) +- One concern per file is preferred (persona routing separate from scope isolation) +- Keep individual files focused (under 50 lines of rule content) +- YAML frontmatter is mandatory + +## Glob Specificity Rules + +| Pattern | Acceptable? | Why | +|---------|:-----------:|-----| +| `src/**/*` | Yes | Targets specific directory | +| `**/*.ts` | Yes | Targets specific file type | +| `src/**/*.tsx` | Yes | Combines directory + type | +| `*` | No | Too broad — would match everything | +| `**/*` | No | Equivalent to matching all files | + +## Pre-Existing File Behavior + +| Scenario | Action | +|----------|--------| +| No `.cursor/rules/` directory | Create directory and add rule files starting at 900 | +| Directory exists with rules | Scan for glob collisions, use next available number | +| Glob collision detected | Report conflict, propose narrower glob or skip | + +Never modify or renumber existing `.mdc` files. + +## Collision Detection Protocol + +Before writing ANY .mdc file: +1. Read all existing `.mdc` files in `.cursor/rules/` +2. Extract each file's `globs` value from frontmatter +3. Compare proposed globs against existing globs +4. If overlap exists: report which file conflicts, what its glob is, and why they conflict +5. Propose alternatives: narrower glob, different file scope, or skip + +## Examples + +### Example 1: Simple project context + +```yaml +--- +description: Project context and quality gates for agentic-os +globs: src/**/* +alwaysApply: true +--- +# Project Standards + +This is a TypeScript project using Vitest for testing. + +When working in src/: +- Run `npm test` before considering work complete +- Run `npm run lint` to verify code style +- New files should have corresponding .test.ts files +``` + +### Example 2: Persona routing (Complex tier) + +```yaml +--- +description: Persona routing — Architecture domain +globs: Designs/**/* +alwaysApply: true +--- +# Architect Mode + +When working in Designs/: +- Prioritize structural scalability and system design patterns +- Reference AGENTS.md for full persona guidelines +- Cross-reference existing blueprints before proposing new designs +- Do not apply patterns from Operations/ or Infrastructure/ +``` + +### Example 3: Scope isolation (Complex tier) + +```yaml +--- +description: Scope isolation between concern domains +globs: Operations/**/*,Designs/**/*,Infrastructure/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in Operations/: +- Do not suggest content from Designs/ or Infrastructure/ + +When working in Designs/: +- Do not suggest content from Operations/ or Infrastructure/ + +When working in Infrastructure/: +- Do not suggest content from Operations/ or Designs/ +``` + +## Usage Context + +The AI reads this adapter when the user has targeted Cursor as a runtime. It formats the assembled proposal (from templates) into Cursor-native `.mdc` files, respecting numbering conventions, glob specificity, and collision detection requirements. diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/agents/openai.yaml new file mode 100644 index 0000000..d13d161 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/agents/openai.yaml @@ -0,0 +1,5 @@ +name: agentic-os-setup +description: AI-assisted repo setup — scans structure, classifies complexity, proposes configuration proportional to detected needs. Use when setting up agentic-os on an existing project. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/catalog.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/catalog.md new file mode 100644 index 0000000..613ec51 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/catalog.md @@ -0,0 +1,213 @@ +# Signal Catalog + +## Purpose + +Structured reference of known filesystem patterns and their meanings. The AI uses this catalog to anchor detection during repo scanning. Patterns not listed here do not prevent the AI from reasoning about novel structures — this is a reference, not a hard gate. + +--- + +## Signal: .cursor/rules/ + +**Pattern:** Directory `.cursor/rules/` exists with `.mdc` files +**Indicates:** Existing Cursor AI configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Scan existing rules for glob patterns (collision detection) +- Detect numbering convention (respect existing band) +- Generate agentic-os rule in next available number slot +**Coexistence:** Additive only — never modify existing rules + +--- + +## Signal: CLAUDE.md + +**Pattern:** File `CLAUDE.md` at repo root +**Indicates:** Existing Claude Code configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Do not overwrite — create `CLAUDE-agentic-os.md` as companion file +- Reference companion from proposal +**Coexistence:** Companion file pattern + +--- + +## Signal: .clinerules + +**Pattern:** File `.clinerules` at repo root +**Indicates:** Existing Cline configuration +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Do not overwrite — create `.clinerules-agentic-os` as companion file +**Coexistence:** Companion file pattern + +--- + +## Signal: AGENTS.md + +**Pattern:** File `AGENTS.md` at repo root +**Indicates:** Existing agent instructions (possibly Antigravity or hand-written) +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Extend with managed block (append below existing content) +- Never replace or modify existing content +**Coexistence:** Managed block append pattern + +--- + +## Signal: _bmad/ + +**Pattern:** Directory `_bmad/` at repo root +**Indicates:** BMad agent framework installed +**Complexity impact:** Automatically Complex tier (framework presence) +**Setup implications:** +- Defer persona routing entirely to BMAD +- Only generate: scope isolation, cross-reference, naming enforcement +- Explain deferral in proposal +**Coexistence:** Defer persona ownership + +--- + +## Signal: .claude/ + +**Pattern:** Directory `.claude/` at repo root +**Indicates:** Claude Code project configuration or skills +**Complexity impact:** +1 existing AI config +**Setup implications:** +- Inspect for skills/ subdirectory +- Note existing configuration approach +**Coexistence:** Do not modify contents + +--- + +## Signal: package.json + +**Pattern:** File `package.json` at repo root +**Indicates:** Node.js/JavaScript project +**Complexity impact:** +1 concern folder (if workspaces found: +1 per workspace root) +**Setup implications:** +- Check for `workspaces` field (monorepo indicator → Multi or Complex) +- Detect test framework (jest, vitest, mocha) for quality gate template +- Note scripts for build/test/lint commands +**Coexistence:** Read-only reference + +--- + +## Signal: pyproject.toml + +**Pattern:** File `pyproject.toml` at repo root +**Indicates:** Python project (modern packaging) +**Complexity impact:** +1 concern folder +**Setup implications:** +- Check for monorepo tools (hatch workspaces, pants) +- Detect test framework (pytest, unittest) +- Note linting tools (ruff, black, mypy) +**Coexistence:** Read-only reference + +--- + +## Signal: Cargo.toml + +**Pattern:** File `Cargo.toml` at repo root +**Indicates:** Rust project +**Complexity impact:** +1 concern folder (if workspace: +1 per member) +**Setup implications:** +- Check for `[workspace]` section (monorepo indicator) +- Note crate structure for scope isolation +**Coexistence:** Read-only reference + +--- + +## Signal: go.mod + +**Pattern:** File `go.mod` at repo root +**Indicates:** Go project +**Complexity impact:** +1 concern folder +**Setup implications:** +- Check for go.work (multi-module workspace) +- Note module path for naming conventions +**Coexistence:** Read-only reference + +--- + +## Signal: terraform/ + +**Pattern:** Directory `terraform/` or `infra/` with `.tf` files +**Indicates:** Infrastructure-as-Code component +**Complexity impact:** +1 concern folder +**Setup implications:** +- Distinct concern domain (infrastructure vs application code) +- Consider scope isolation between IaC and app code +- Note state backend for quality gate template +**Coexistence:** Read-only reference + +--- + +## Signal: docker-compose.yml + +**Pattern:** File `docker-compose.yml` or `docker-compose.yaml` at root +**Indicates:** Multi-service local development setup +**Complexity impact:** +1 concern folder (if 3+ services) +**Setup implications:** +- Indicates multiple services that may need scope isolation +- Service names can inform persona routing +**Coexistence:** Read-only reference + +--- + +## Signal: .github/ + +**Pattern:** Directory `.github/` with workflows/ +**Indicates:** GitHub Actions CI/CD pipeline +**Complexity impact:** Neutral (doesn't affect tier directly) +**Setup implications:** +- Note CI structure for quality gate template +- Detect workflow organization patterns +**Coexistence:** Read-only reference + +--- + +## Signal: docs/ + +**Pattern:** Directory `docs/` at root +**Indicates:** Documentation as a distinct concern +**Complexity impact:** +1 concern folder +**Setup implications:** +- Potential scope isolation (docs vs code) +- May indicate architectural documentation needs +**Coexistence:** Read-only reference + +--- + +## Signal: Makefile + +**Pattern:** File `Makefile` at repo root +**Indicates:** Build automation (often multi-concern orchestration) +**Complexity impact:** Neutral (indicator of maturity, not complexity) +**Setup implications:** +- Read target names for project structure hints +- Note common targets (build, test, lint, deploy) +**Coexistence:** Read-only reference + +--- + +## Signal: src/ + +**Pattern:** Directory `src/` at repo root (without other concern folders) +**Indicates:** Single-purpose project with conventional structure +**Complexity impact:** Neutral (alone = Simple tier cap) +**Setup implications:** +- If `src/` is the only concern folder, tier should not exceed Simple +- Common in libraries, CLI tools, single applications +**Coexistence:** Read-only reference + +--- + +## Usage Context + +The AI reads this catalog during the scanning phase to: +1. Identify which signals are present in the target repo +2. Map each signal to its complexity dimension contribution +3. Determine coexistence behavior before proposing any output +4. Anchor decisions in documented patterns rather than hallucination + +Signals not in this catalog can still be reasoned about — this catalog accelerates recognition of common patterns but does not limit the AI's analytical capability. diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/examples/complex-output.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/examples/complex-output.md new file mode 100644 index 0000000..73137f7 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/examples/complex-output.md @@ -0,0 +1,150 @@ +# Calibration Example: Complex Tier Output + +## Scenario + +A multi-concern monorepo with `Designs/`, `Operations/`, `Team-Workitems/`, `Infrastructure/`, and `docs/` at root. Existing `.cursor/rules/` (files 800-805), existing AGENTS.md. Two team indicators. Cross-references between Operations and Designs. + +**Detected signals:** .cursor/rules/ (6 files, 800-band), AGENTS.md, 5 concern folders, team indicators, cross-domain references +**Classification:** Complex (5+ concern folders, 4+ AI configs, 2 teams, 2+ cross-refs) +**Runtimes targeted:** claude, cursor, antigravity + +## Expected Output + +### File: CLAUDE-agentic-os.md (companion — existing CLAUDE.md untouched) + +```markdown +# Agentic-OS Configuration + +## Persona Routing + +- **Architect Mode:** Triggered when editing `/Designs/`. Prioritize structural scalability, system design patterns, and requirements traceability. +- **Operations Mode:** Triggered when editing `/Operations/`. Focus on process efficiency, candidate assessment, and documentation completeness. +- **Engineering Mode:** Triggered when editing `/Infrastructure/`. Focus on reliability, security, and operational readiness. + +See AGENTS.md for full persona definitions. + +## Scope Isolation + +The following domains are isolated — do not cross-reference unless explicitly asked: +- `/Designs/` and `/Operations/` are independent concerns +- `/Infrastructure/` and `/Team-Workitems/` are independent concerns + +## Cross-Reference Rules + +- **Operations/ → Designs/**: Interview files must reference a valid job description via `Job-ID:` frontmatter field +- **Team-Workitems/ → Designs/**: Work items should trace to design documents via `Design-Ref:` field + +## Naming Conventions + +### Operations/job-interviews/ +- Candidate files: `candidate_[first-name]-[last-name].md` + +### Team-Workitems/ +- Work items: `[priority]-[short-description].md` + +## Quality Gates + +Before completing work, verify: +- **Linting**: `make lint` +- **Tests**: `make test` +- **Cross-references**: Verify linked documents exist +``` + +### File: .cursor/rules/806-agentic-os-personas.mdc + +```yaml +--- +description: Persona routing for agentic-os domains — Designs +globs: Designs/**/* +alwaysApply: true +--- +# Architect Mode + +When working in Designs/: +- Prioritize structural scalability and system design metrics +- Reference AGENTS.md for architecture persona guidelines +- Cross-reference parent blueprints for requirements traceability +- Do not suggest patterns from Operations/ or Infrastructure/ +``` + +### File: .cursor/rules/807-agentic-os-isolation.mdc + +```yaml +--- +description: Scope isolation between concern domains +globs: Operations/**/*,Designs/**/*,Team-Workitems/**/*,Infrastructure/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in Operations/: +- Do not read or suggest content from Designs/ or Infrastructure/ +- Keep completions scoped to HR/recruitment conventions + +When working in Designs/: +- Do not read or suggest content from Operations/ or Team-Workitems/ +- Keep completions scoped to architecture patterns + +When working in Infrastructure/: +- Do not read or suggest content from Operations/ or Designs/ +- Keep completions scoped to IaC and deployment patterns +``` + +### File: AGENTS.md (extended via managed block — existing content preserved above) + +```markdown + +## Agentic-OS Generated Rules + +### Personas + +#### Architect +**Scope:** `/Designs/` +**Focus:** System design, scalability, requirements traceability +**Behavioral rules:** +- Prioritize structural patterns over quick fixes +- Reference existing blueprints before proposing new structures +- Validate against design principles in docs/ + +#### Operations Specialist +**Scope:** `/Operations/` +**Focus:** Process efficiency, documentation completeness, candidate assessment +**Behavioral rules:** +- Follow HR documentation standards +- Enforce cross-reference rules (interviews → job descriptions) +- Maintain naming conventions strictly + +#### Infrastructure Engineer +**Scope:** `/Infrastructure/` +**Focus:** Reliability, security, operational readiness +**Behavioral rules:** +- Validate against security baselines +- Consider blast radius of changes +- Reference runbooks for operational procedures + +### Scope Boundaries + +| Domain | Isolated From | Rationale | +|--------|--------------|-----------| +| Designs/ | Operations/, Team-Workitems/ | Architecture concerns are independent of HR operations | +| Operations/ | Designs/, Infrastructure/ | Recruitment is independent of system design | +| Infrastructure/ | Operations/, Designs/ | IaC has distinct safety requirements | + +### Cross-References + +| Source | Target | Link Format | Rule | +|--------|--------|-------------|------| +| Operations/job-interviews/ | Operations/job-descriptions/ | `Job-ID: jd-*` | Every interview file must link to a valid JD | +| Team-Workitems/ | Designs/ | `Design-Ref: *` | Work items should trace to design docs | + + +``` + +## Volume Calibration + +Complex tier output should be: +- Multiple config files per runtime (personas, isolation, cross-refs may be separate) +- AGENTS.md with full persona definitions and relationship tables +- 50-150 lines per major file +- Comprehensive organizational rules covering personas, isolation, cross-references, and naming +- Cursor rules in separate files by concern (personas, isolation) to avoid glob conflicts diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/examples/simple-output.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/examples/simple-output.md new file mode 100644 index 0000000..72a5545 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/examples/simple-output.md @@ -0,0 +1,65 @@ +# Calibration Example: Simple Tier Output + +## Scenario + +A single-purpose Node.js project with `src/`, `tests/`, `package.json`, and a `.github/workflows/` directory. No existing AI config. One developer. + +**Detected signals:** package.json (jest, eslint), src/, .github/ +**Classification:** Simple (1 concern folder, 0 AI configs, 0 teams, 0 cross-refs, no framework) +**Runtimes targeted:** claude, cursor + +## Expected Output + +### File: CLAUDE.md + +```markdown +# Project Context + +This is a Node.js project using Jest for testing and ESLint for linting. + +## Quality Gates + +Before completing work: +- Run tests: `npm test` +- Run linting: `npm run lint` +- Ensure new code has corresponding test coverage + +## Project Structure + +- `src/` — Application source code +- `tests/` — Test files (Jest) +- `.github/workflows/` — CI pipeline +``` + +### File: .cursor/rules/900-agentic-os.mdc + +```yaml +--- +description: Project context and quality gates for agentic-os +globs: src/**/* +alwaysApply: true +--- +# Project Standards + +This is a Node.js project. When working in src/: +- Run `npm test` before considering work complete +- Run `npm run lint` to verify code style +- New source files should have corresponding test files in tests/ +- Follow existing naming conventions in src/ +``` + +## What is NOT Generated (Simple Tier) + +- No AGENTS.md (not enough complexity for personas) +- No GOALS.md (not a multi-concern workspace) +- No persona routing (single domain) +- No scope isolation (single domain) +- No cross-reference enforcement (no relationships detected) + +## Volume Calibration + +Simple tier output should be: +- 1 file per targeted runtime +- Under 30 lines per file +- Focused on project context and quality gates only +- No organizational/behavioral rules diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/cross-reference.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/cross-reference.md new file mode 100644 index 0000000..e61e739 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/cross-reference.md @@ -0,0 +1,61 @@ +# Template: Cross-Reference Enforcement + +## Intent + +Enforce that files in one domain correctly reference files in another domain where a declared relationship exists. Catches broken links, missing references, and orphaned documents. + +## Inputs Required + +- `{relationships}`: List of source → target relationships with their linking mechanism +- `{source_domain}`: Domain where the referencing file lives +- `{target_domain}`: Domain where the referenced file lives +- `{link_format}`: How the reference is expressed (frontmatter field, inline link, filename convention) + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Cross-reference enforcement — {source_domain} → {target_domain} +globs: {source_domain}/**/* +alwaysApply: true +--- +# Cross-Reference Rules + +Every file in `{source_domain}/` that matches `{file_pattern}` MUST: +- {reference_requirement_1} +- {reference_requirement_2} + +Validation: +- Check that referenced {target_domain} file exists +- Warn if reference format doesn't match: `{link_format}` +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Cross-Reference Rules + +{for each relationship} +- **{source_domain}/ → {target_domain}/**: Files matching `{file_pattern}` must contain a reference to a valid `{target_domain}` file using format: `{link_format}` +{end for} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Relationship Enforcement + +{for each relationship} +### {relationship_name} +**Source:** `/{source_domain}/{file_pattern}` +**Target:** `/{target_domain}/` +**Link format:** `{link_format}` +**Rule:** {enforcement_description} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** Cross-domain references found (e.g., interview files referencing job descriptions, work items referencing design docs, tests referencing source modules) +- **Requires:** User confirmation for AI-inferred relationships (only manifest-declared relationships are auto-included) diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/naming-enforcement.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/naming-enforcement.md new file mode 100644 index 0000000..b0b0890 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/naming-enforcement.md @@ -0,0 +1,67 @@ +# Template: Naming Enforcement + +## Intent + +Enforce consistent file and directory naming conventions within a domain. Catches deviations from established patterns and guides creation of new files. + +## Inputs Required + +- `{domain}`: Domain path where naming rules apply +- `{patterns}`: List of naming patterns with their regex or description +- `{examples}`: Valid and invalid filename examples + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Naming conventions for {domain} +globs: {domain}/**/* +alwaysApply: true +--- +# Naming Conventions + +Files in `{domain}/` follow these patterns: + +{for each pattern} +- **{file_type}**: `{naming_pattern}` + Example: `{valid_example}` +{end for} + +When creating new files in this domain: +- Follow the naming pattern exactly +- Warn if a proposed filename doesn't match the convention +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Naming Conventions + +{for each domain_with_patterns} +### {domain}/ +{for each pattern} +- `{file_type}` files: `{naming_pattern}` (e.g., `{valid_example}`) +{end for} +{end for} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Naming Standards + +{for each domain_with_patterns} +### {domain} +| File Type | Pattern | Example | +|-----------|---------|---------| +{for each pattern} +| {file_type} | `{naming_pattern}` | `{valid_example}` | +{end for} +{end for} +``` + +## When to Use + +- **Complexity tier:** Simple, Multi, or Complex (applicable at any tier where patterns are detected) +- **Detected signals:** Consistent naming patterns observed in existing files (3+ files following same convention) +- **Common patterns:** kebab-case files, prefixed files (NNN-name.ext), date-prefixed (YYYY-MM-DD-name), type-prefixed (feat-*, fix-*) diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/persona-routing.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/persona-routing.md new file mode 100644 index 0000000..9c69303 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/persona-routing.md @@ -0,0 +1,66 @@ +# Template: Persona Routing + +## Intent + +Route AI persona/behavior based on which folder the user is editing in. Each concern domain gets a distinct behavioral mode optimized for that domain's work. + +## Inputs Required + +- `{domains}`: List of detected concern domains with their folder paths +- `{personas}`: Mapping of domain → persona name and behavioral description +- `{repo_name}`: Repository name for context + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Persona routing for agentic-os domains — {domain_name} +globs: {domain_path}/**/* +alwaysApply: true +--- +# {persona_name} Mode + +When working in `{domain_path}/`: +- {persona_behavioral_rule_1} +- {persona_behavioral_rule_2} +- {persona_behavioral_rule_3} + +Reference AGENTS.md for full persona guidelines. +``` + +One .mdc file per domain. Each gets a specific glob. + +## Output Pattern (CLAUDE.md section) + +```markdown +## Persona Routing + +{for each domain} +- **{persona_name} Mode:** Triggered when editing `/{domain_path}/`. {persona_behavioral_summary} +{end for} + +See AGENTS.md for full persona definitions. +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Personas + +{for each domain} +### {persona_name} + +**Scope:** `/{domain_path}/` +**Focus:** {persona_focus_description} +**Behavioral rules:** +- {rule_1} +- {rule_2} +- {rule_3} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** 2+ distinct concern domains with different intent (e.g., `Designs/` + `Operations/` or `frontend/` + `backend/` + `infra/`) +- **NOT when:** Single-purpose repo, or `_bmad/` detected (defer persona ownership to BMAD) diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/quality-gates.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/quality-gates.md new file mode 100644 index 0000000..35d64c3 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/quality-gates.md @@ -0,0 +1,72 @@ +# Template: Quality Gates + +## Intent + +Define quality checks that the AI should enforce or remind about when creating or modifying files within a domain. Derived from detected tooling (linters, test frameworks, CI pipelines). + +## Inputs Required + +- `{domain}`: Domain path or glob where quality gates apply +- `{gates}`: List of quality checks with their commands or descriptions +- `{test_framework}`: Detected test framework (jest, pytest, cargo test, go test, etc.) +- `{lint_tools}`: Detected linting/formatting tools +- `{ci_checks}`: Known CI pipeline checks + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Quality gates for {domain} +globs: {domain}/**/*.{extensions} +alwaysApply: true +--- +# Quality Gates + +Before considering work in `{domain}/` complete: + +{for each gate} +- [ ] {gate_description}: `{gate_command}` +{end for} + +When creating new files: +- Ensure they have corresponding test files (if test framework detected) +- Follow existing patterns for test file location and naming +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Quality Gates + +Before completing work, verify: + +{for each gate} +- **{gate_name}**: `{gate_command}` — {gate_purpose} +{end for} + +Test framework: {test_framework} +Test location: {test_directory_pattern} +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Quality Standards + +### Pre-Completion Checklist +{for each gate} +- [ ] **{gate_name}**: {gate_description} + Command: `{gate_command}` +{end for} + +### Testing Requirements +- Framework: {test_framework} +- Location: `{test_directory_pattern}` +- Coverage: {coverage_expectations} +``` + +## When to Use + +- **Complexity tier:** Simple, Multi, or Complex +- **Detected signals:** Test framework present (package.json scripts, pytest.ini, Cargo.toml test config), linting tools configured (.eslintrc, ruff.toml, .golangci.yml), CI workflows present (.github/workflows/) +- **Scales with tier:** Simple = test + lint only; Multi/Complex = full gate set including build verification diff --git a/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/scope-isolation.md b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/scope-isolation.md new file mode 100644 index 0000000..d3ba8e3 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/agentic-os-setup/templates/scope-isolation.md @@ -0,0 +1,64 @@ +# Template: Scope Isolation + +## Intent + +Prevent AI from cross-contaminating context between unrelated concern domains. When working in one domain, the AI should not suggest content from or reference patterns in other domains unless explicitly asked. + +## Inputs Required + +- `{domains}`: List of domain paths that should be isolated from each other +- `{isolation_pairs}`: Specific pairs of domains that must not cross-reference + +## Output Pattern (Cursor .mdc) + +```yaml +--- +description: Scope isolation between concern domains +globs: {domain_path_1}/**/*,{domain_path_2}/**/* +alwaysApply: true +--- +# Cross-Domain Isolation + +When working in `{domain_path_1}/`: +- Do not read or suggest content from {other_domains} +- Do not apply patterns from {other_domains} to this domain +- Keep completions scoped to this domain's conventions + +When working in `{domain_path_2}/`: +- Do not read or suggest content from {other_domains} +- Do not apply patterns from {other_domains} to this domain +- Keep completions scoped to this domain's conventions +``` + +## Output Pattern (CLAUDE.md section) + +```markdown +## Scope Isolation + +The following domains are isolated — do not cross-reference unless explicitly asked: + +{for each isolation_pair} +- `/{domain_a}/` and `/{domain_b}/` are independent concerns +{end for} + +When editing in one domain, restrict suggestions and completions to that domain's patterns and conventions. +``` + +## Output Pattern (AGENTS.md section) + +```markdown +## Scope Boundaries + +{for each domain} +### {domain_name} +**Path:** `/{domain_path}/` +**Isolated from:** {list_of_other_domains} +**Rationale:** {why_these_are_separate_concerns} +{end for} +``` + +## When to Use + +- **Complexity tier:** Multi or Complex +- **Detected signals:** 2+ concern domains that serve different purposes (e.g., infrastructure vs application code, documentation vs implementation) +- **Always pair with:** Persona Routing (if personas are generated, isolation prevents persona bleed) diff --git a/examples/uj-3-flask-simple/.agents/skills/assumption-mapping/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/assumption-mapping/SKILL.md new file mode 100644 index 0000000..89e444a --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/assumption-mapping/SKILL.md @@ -0,0 +1,65 @@ +--- +name: assumption-mapping +description: Surface and categorize assumptions underlying product strategy. Use early in development to document what you're betting on. +--- + +# Assumption Mapping + +Generate and categorize assumptions underlying a product strategy. + +## When to Use + +Early in product development to surface and document what you're betting on. + +## The Framework + +Organize assumptions into four categories: + +| Category | Focus | Example Questions | +|----------|-------|-------------------| +| **Desirability** | Will users want this? | Problem severity, willingness to pay, switching triggers | +| **Feasibility** | Can we build it? | Technical risks, data needs, integrations, security | +| **Viability** | Will it make money? | Pricing, margins, retention, unit economics | +| **Usability** | Can users use it? | Task success, learnability, error tolerance | + +## The Process + +### 1. Gather Inputs + +Document: +- Product description +- Core problem being solved +- Target user + +### 2. Generate Assumptions + +For each category, create at least 5 assumptions: + +**Format:** +- Statement: "We believe that [specific, falsifiable claim]" +- Impact if wrong: [concrete consequence] + +**Good example:** +- Statement: "We believe that SMB admins will pay $20/user/month if onboarding drops below 30 minutes" +- Impact if wrong: Premium pricing underperforms due to insufficient WTP + +### 3. Quality Check + +Each assumption should be: +- Specific (include numbers, segments, timeframes) +- Testable (you could run an experiment) +- One idea per assumption (no compound claims) + +## Output + +Four lists of 5+ assumptions each: +- Desirability assumptions +- Feasibility assumptions +- Viability assumptions +- Usability assumptions + +Each with statement and impact if wrong. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/assumption-mapping/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/assumption-mapping/agents/openai.yaml new file mode 100644 index 0000000..d606257 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/assumption-mapping/agents/openai.yaml @@ -0,0 +1,5 @@ +name: assumption-mapping +description: Surface and categorize assumptions underlying product strategy. Use early in development to document what you're betting on. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/assumption-prioritization/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/assumption-prioritization/SKILL.md new file mode 100644 index 0000000..ecfa95b --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/assumption-prioritization/SKILL.md @@ -0,0 +1,66 @@ +--- +name: assumption-prioritization +description: Prioritize assumptions by risk and importance. Use after assumption mapping to decide what to test first. +--- + +# Assumption Prioritization + +Prioritize assumptions to focus validation efforts on what matters most. + +## When to Use + +After assumption mapping, to decide which assumptions to test first. + +## The Framework + +Score each assumption on two dimensions: + +**Importance (1-5):** Business impact if false +- 5 = Strategy fails, >20% revenue hit +- 4 = Major adoption/cost driver (10-20%) +- 3 = Moderate impact (5-10%) +- 2 = Minor impact (<5%) +- 1 = Negligible + +**Certainty (1-5):** Evidence that it's true +- 1 = No evidence, conjecture +- 2 = Anecdotes, untested +- 3 = Early signals, small samples +- 4 = Strong directional data +- 5 = Robust evidence, production proof + +**Risk Score = Importance x (6 - Certainty)** + +Higher score = riskier assumption = test first + +## The Process + +### 1. Score Each Assumption + +Consider: +- Impact severity from "impact if wrong" +- Blast radius (users/systems affected) +- Irreversibility (cost to fix later) +- Dependencies (does it block others?) +- Evidence quality + +### 2. Map to Quadrants + +| | Low Certainty | High Certainty | +|---|---|---| +| **High Importance** | TEST FIRST | Monitor | +| **Low Importance** | Deprioritize | Ignore | + +### 3. Rank by Risk Score + +Focus validation on High Importance / Low Certainty assumptions. + +## Output + +- 2x2 summary with counts per quadrant +- Top risks ranked by score with rationale +- Full ranked list of all assumptions + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/assumption-prioritization/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/assumption-prioritization/agents/openai.yaml new file mode 100644 index 0000000..f31a352 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/assumption-prioritization/agents/openai.yaml @@ -0,0 +1,5 @@ +name: assumption-prioritization +description: Prioritize assumptions by risk and importance. Use after assumption mapping to decide what to test first. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/atlassian-jira-sync/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/atlassian-jira-sync/SKILL.md new file mode 100644 index 0000000..71a7ff0 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/atlassian-jira-sync/SKILL.md @@ -0,0 +1,98 @@ +--- +name: atlassian-jira-sync +description: Sync Jira issues with local tasks. Use during daily planning or when user asks about Jira issues. +--- + +# Jira Issue Sync + +Check Jira for assigned issues and sync with local task management. + +## Instructions + +### Step 1: Fetch Assigned Issues + +Call `jira_search` with JQL: +``` +assignee = currentUser() AND status != Done ORDER BY priority DESC +``` + +### Step 2: Compare with Local Tasks + +Check `Tasks/` for existing files with Jira references: +- Look for `jira_key` in YAML frontmatter +- Identify new issues not yet in Tasks/ + +### Step 3: Present Summary + +``` +Jira Issues (8 active): + +**Blockers/Critical** +- PROJ-123: Production bug in auth [In Progress] + +**High Priority** +- PROJ-124: API rate limiting [To Do] +- PROJ-125: Update deployment docs [In Review] + +**Normal** +- PROJ-126: Refactor logging [Backlog] + +3 issues not yet in local Tasks. Create them? +``` + +### Step 4: Sync Options + +| Option | Description | +|--------|-------------| +| Create all | Add all new issues as local tasks | +| Select specific | Choose which to sync | +| Skip | Continue without syncing | + +### Step 5: Create Local Tasks + +For each issue to sync, create task file: + +```yaml +--- +title: [Issue summary] +category: technical +priority: [Map from Jira priority] +status: n +jira_key: PROJ-XXX +--- +``` + +## Priority Mapping + +| Jira | Personal OS | +|------|-------------| +| Blocker | P0 | +| Critical | P0 | +| High | P1 | +| Medium | P2 | +| Low | P3 | + +## Example Flow + +**User:** "What should I work on today?" + +**Agent:** +1. Fetches Jira issues +2. Compares with local tasks +3. "You have 5 Jira tickets..." +4. Offers to create local tasks +5. Continues with planning + +## Notes + +- Keep `jira_key` in frontmatter for bidirectional sync +- Update Jira status when local task completes +- Include Jira link in task context section + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/atlassian-jira-sync/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/atlassian-jira-sync/agents/openai.yaml new file mode 100644 index 0000000..8482a2b --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/atlassian-jira-sync/agents/openai.yaml @@ -0,0 +1,5 @@ +name: atlassian-jira-sync +description: Sync Jira issues with local tasks. Use during daily planning or when user asks about Jira issues. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/backend-design/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/backend-design/SKILL.md new file mode 100644 index 0000000..aa3964f --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/backend-design/SKILL.md @@ -0,0 +1,96 @@ +--- +name: backend-design +description: Design backend architecture for implementation with API contracts, data model changes, service boundaries, security, and observability. +--- + +# Backend Design + +Use this skill to design robust backend changes before implementation. + +## The Process + +### Step 1: Define backend objective + +Clarify: +- business objective +- service boundary +- latency/reliability expectations + +### Step 2: Define API and contract changes + +Specify: +- endpoints/events +- request/response schemas +- error model and status mapping + +### Step 3: Define data model and migrations + +Document: +- schema changes +- migration strategy +- backward-compatibility approach + +### Step 4: Define security and observability + +Include: +- authn/authz requirements +- rate limiting/abuse controls +- logging, metrics, tracing +- alerting conditions + +### Step 5: Define rollout and verification + +Provide: +- phased rollout or feature flags +- rollback strategy +- verification checks and commands + +## Output Format + +```markdown +# [Feature Name] Backend Design Spec + +## Objective +- Goal: +- Service boundary: + +## API Contracts +- Endpoint/event definitions: +- Request/response schema: +- Error model: + +## Data Model +- Schema changes: +- Migration plan: +- Compatibility notes: + +## Security and Reliability +- Authn/authz: +- Abuse controls: +- Reliability constraints: + +## Observability +- Logs: +- Metrics: +- Traces: +- Alerts: + +## Rollout and Verification +- Rollout plan: +- Rollback plan: +- Verification commands/evidence: +``` + +## Quality Bar + +- Contracts must be explicit and testable +- Migration and rollback must be present for schema changes +- Verification must include observable evidence + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/backend-design/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/backend-design/agents/openai.yaml new file mode 100644 index 0000000..e7d3151 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/backend-design/agents/openai.yaml @@ -0,0 +1,5 @@ +name: backend-design +description: Design backend architecture for implementation with API contracts, data model changes, service boundaries, security, and observability. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/brainstorming/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/brainstorming/SKILL.md new file mode 100644 index 0000000..829b1bf --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/brainstorming/SKILL.md @@ -0,0 +1,60 @@ +--- +name: brainstorming +description: Turn ideas into designs through collaborative dialogue. Use before any creative work - features, components, or modifications. +--- + +# Brainstorming Ideas Into Designs + +Use this before any creative work - creating features, building components, adding functionality, or modifying behavior. + +## Overview + +Turn ideas into fully formed designs through collaborative dialogue. Understand before implementing. + +## The Process + +**Understanding the idea:** +- Check out current project state first (files, docs, recent changes) +- Ask questions one at a time to refine the idea +- Prefer multiple choice questions when possible +- Only one question per message - break complex topics into multiple questions +- Focus on: purpose, constraints, success criteria + +**Exploring approaches:** +- Propose 2-3 different approaches with trade-offs +- Lead with your recommended option and explain why +- Present options conversationally + +**Presenting the design:** +- Once you understand what you're building, present the design +- Break into sections of 200-300 words +- Ask after each section whether it looks right +- Cover: architecture, components, data flow, error handling, testing +- Be ready to go back and clarify if something doesn't make sense + +## After the Design + +**Documentation:** +- Write the validated design to a planning document +- Commit the design before starting implementation + +**Implementation:** +- Ask: "Ready to set up for implementation?" +- Use `writing-plans.md` skill to create detailed implementation plan + +## Key Principles + +- **One question at a time** - Don't overwhelm with multiple questions +- **Multiple choice preferred** - Easier to answer when possible +- **YAGNI ruthlessly** - Remove unnecessary features from designs +- **Explore alternatives** - Always propose 2-3 approaches before settling +- **Incremental validation** - Present design in sections, validate each +- **Be flexible** - Go back and clarify when something doesn't make sense + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/brainstorming/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/brainstorming/agents/openai.yaml new file mode 100644 index 0000000..07f3118 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/brainstorming/agents/openai.yaml @@ -0,0 +1,5 @@ +name: brainstorming +description: Turn ideas into designs through collaborative dialogue. Use before any creative work - features, components, or modifications. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/challenging-stakeholder-questions/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/challenging-stakeholder-questions/SKILL.md new file mode 100644 index 0000000..c23f876 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/challenging-stakeholder-questions/SKILL.md @@ -0,0 +1,34 @@ +--- +name: challenging-stakeholder-questions +description: Generate rigorous stakeholder challenge questions for proposal or meeting preparation. +--- + +# Challenging Stakeholder Questions + +Generate probing questions that pressure-test a proposal. + +## Instructions + +### Step 1: Parse context +- Use goal/context and stakeholder details. +- State assumptions if details are missing. + +### Step 2: Generate question set +- Produce at least 20 non-redundant questions. +- Cover: financials, resources, timeline, risks, market, competition, feasibility, UX, ethics, sustainability, team capability, performance history, strategic alignment, compliance, scalability. + +### Step 3: Check quality +- Remove generic and repetitive questions. +- Ensure each question ties to provided context. + +## Output + +- Numbered question list (20+) + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/challenging-stakeholder-questions/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/challenging-stakeholder-questions/agents/openai.yaml new file mode 100644 index 0000000..82a5b82 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/challenging-stakeholder-questions/agents/openai.yaml @@ -0,0 +1,5 @@ +name: challenging-stakeholder-questions +description: Generate rigorous stakeholder challenge questions for proposal or meeting preparation. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/competitor-analysis/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/competitor-analysis/SKILL.md new file mode 100644 index 0000000..be63598 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/competitor-analysis/SKILL.md @@ -0,0 +1,76 @@ +--- +name: competitor-analysis +description: Analyze competitors using Porter's four-component model - drivers, assumptions, strategy, capabilities. +--- + +# Competitor Analysis (Porter) + +Analyze competitors using Porter's four-component model. + +## When to Use + +When you need to understand a competitor's strategy, capabilities, and likely moves. + +## The Framework + +Porter's four components: + +| Component | Questions | +|-----------|-----------| +| **Objectives** | What are they trying to achieve? (growth, profit, share, positioning) | +| **Current Strategy** | How are they competing? (segments, pricing, channels, roadmap) | +| **Assumptions** | What do they believe about the market, themselves, and rivals? | +| **Capabilities** | What can they actually do? (resources, competencies, gaps) | + +## The Process + +### 1. Objectives (Future Goals) +- Economic goals (growth, profitability, market share) +- Strategic goals (positioning, tech leadership, ecosystem) +- Timeframes and indicators +- Priority ranking + +### 2. Current Strategy +- Target segments and value proposition +- Pricing and monetization +- Go-to-market (channels, partnerships) +- Product roadmap themes +- Geographic posture + +### 3. Assumptions +- About the industry (demand, regulation, tech trajectory) +- About themselves (core competencies, cost position) +- About you and other rivals +- Implicit beliefs inferred from behavior + +### 4. Capabilities +- Tangible: cost structure, capacity, balance sheet +- Intangible: brand, IP, data, culture, talent +- Activities across value chain +- Notable gaps and constraints + +### 5. Synthesize: Likely Moves + +Based on the four components: +- What will they respond to quickly vs. ignore? +- Probable near-term moves (ranked by likelihood) +- Expected response speed by move type + +### 6. Implications for Us +- Risks to monitor +- Opportunities to exploit +- Recommended counter-moves +- "If they do X, we do Y" mapping + +## Output + +- Executive snapshot +- Four components analysis +- Likely moves and response profile +- Implications and recommendations +- Evidence sources +- Unknowns and validation plan + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/competitor-analysis/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/competitor-analysis/agents/openai.yaml new file mode 100644 index 0000000..7d1ad0d --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/competitor-analysis/agents/openai.yaml @@ -0,0 +1,5 @@ +name: competitor-analysis +description: Analyze competitors using Porter's four-component model - drivers, assumptions, strategy, capabilities. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/crux-diagnosis/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/crux-diagnosis/SKILL.md new file mode 100644 index 0000000..c5b5135 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/crux-diagnosis/SKILL.md @@ -0,0 +1,71 @@ +--- +name: crux-diagnosis +description: Identify the pivotal obstacle between current state and desired future. Use when developing strategy. +--- + +# Strategic Crux Diagnosis + +Identify the pivotal obstacle between current state and desired future. + +## When to Use + +When developing strategy or facing complex strategic decisions. + +## The Concept + +**Crux:** The smallest set of obstacles that, if solved, makes everything else tractable or unnecessary. + +## Required Inputs + +Gather before analysis: +- Current state (baseline metrics, capabilities) +- Desired future (time-bound outcome, targets) +- Constraints (budget, headcount, tech, compliance) +- Available assets (data, channels, IP, partnerships) +- Key risks and non-negotiables + +## The Process + +### 1. Map Current to Future + +Create a causal graph: +- Start: Current state +- End: Desired future +- List all blockers in between + +### 2. Score Each Blocker + +Evaluate on: +- **Causal centrality:** How much else depends on this? +- **Bottleneck severity:** How much does it slow everything? +- **Solvability:** Can we actually fix it? +- **Leverage potential:** If solved, how much unlocks? +- **Time to impact:** How fast could we see results? +- **Evidence strength:** How sure are we this is the problem? + +### 3. Identify the Crux + +Find the blocker(s) where: +- Solving it unlocks the most downstream progress +- It's actually solvable given constraints +- Time to impact is acceptable + +### 4. Generate Strategic Options + +Create 4-7 options aimed at the crux: +- Include at least one non-obvious approach +- Include at least one constraint-relaxation option +- Evaluate against decision criteria + +## Output + +- Executive summary (situation, crux, approach) +- Evidence pack (facts, assumptions, uncertainties) +- Crux definition with scoring +- Options comparison table +- Chosen strategy with rationale +- Strategic moves (3-5) with owners and timelines + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/crux-diagnosis/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/crux-diagnosis/agents/openai.yaml new file mode 100644 index 0000000..bd574ed --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/crux-diagnosis/agents/openai.yaml @@ -0,0 +1,5 @@ +name: crux-diagnosis +description: Identify the pivotal obstacle between current state and desired future. Use when developing strategy. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/davci/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/davci/SKILL.md new file mode 100644 index 0000000..e6bab28 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/davci/SKILL.md @@ -0,0 +1,83 @@ +--- +name: davci +description: Define clear decision rights - Decider, Approver, Veto, Consulted, Informed. Use when clarifying who decides. +--- + +# DAVCI Decision Rights + +Define clear decision rights using the DAVCI framework. + +## When to Use + +When you need to clarify who decides, approves, and must be consulted on a decision. + +## The Framework + +| Role | Definition | Rules | +|------|------------|-------| +| **D - Decider** | Single person accountable for outcome | Exactly one per decision | +| **A - Approver** | Can override the Decider | Optional; cannot be the D | +| **V - Veto** | Can block for specific domain | One per domain; time-boxed | +| **C - Consulted** | Has input before decision | Keep to 5 or fewer | +| **I - Informed** | Needs to know after decision | Keep targeted | + +## The Process + +### 1. Define the Decision Object + +Be specific about what's being decided: +- Clear title +- Concrete deadline +- Decision type (Strategy, Scope, Design, Technical, Process, Risk, Commercial) + +### 2. Assign Roles + +**Decider (D):** +- Who is accountable for the outcome? +- Must be one person only + +**Approver (A):** +- Does D need air cover for risk/budget/politics? +- If yes, name person one level up + +**Veto (V):** +- Which domains apply? (Security, Legal, Privacy, Brand, Compliance) +- One person per domain +- Set veto window (default: 48 hours) + +**Consulted (C):** +- Who has unique information to improve the decision? +- Cap at 5; merge by role if needed + +**Informed (I):** +- Who must act after or needs awareness? +- Keep targeted to those who need it + +### 3. Add Decision Metadata + +- **Deadline:** Date and time +- **Escalation:** If blocked 24h, escalate to whom? +- **Success test:** One checkable sentence +- **Comms plan:** Channel, audience, timing + +## Output Format + +``` +Decision: [title] +Deadline: [date/time] +Type: [Strategy/Scope/Design/Technical/Process/Risk/Commercial] + +D: [name, role] +A: [name, role] or None +V: [Domain - name, window hours] +C: [role/name]; [role/name] +I: [role/name]; [role/name] + +Escalation: [name, role] +Success test: [single checkable sentence] +Comms: [channel + audience + timing] +``` + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/davci/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/davci/agents/openai.yaml new file mode 100644 index 0000000..a32c318 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/davci/agents/openai.yaml @@ -0,0 +1,5 @@ +name: davci +description: Define clear decision rights - Decider, Approver, Veto, Consulted, Informed. Use when clarifying who decides. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/decision-journal/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/decision-journal/SKILL.md new file mode 100644 index 0000000..7374968 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/decision-journal/SKILL.md @@ -0,0 +1,63 @@ +--- +name: decision-journal +description: Create structured records of decisions with expected outcomes, probabilities, and quit conditions. Use for important decisions. +--- + +# Decision Journal + +Create structured records of decisions for learning and accountability. + +## When to Use + +When making important decisions that you want to track and learn from. + +## The Framework + +Record these components for each decision: + +### 1. Expected Outcomes +List 3-5 possible outcomes: +- Best case scenario +- Most likely scenario +- Worst case scenario +- Consider short and long-term + +### 2. Probability Estimates +For each outcome, estimate likelihood (must sum to 100%): +- Outcome A: X% +- Outcome B: Y% +- etc. + +### 3. Key Assumptions +List 3-5 critical assumptions: +- What beliefs underlie this decision? +- Which, if wrong, would change the outcome? + +### 4. Base Rates +Research relevant statistics: +- What's typical for this type of decision? +- Historical data or industry averages? +- What do similar situations suggest? + +### 5. Quit Conditions +Define 2-3 triggers to abandon or change course: +- Clear, measurable indicators +- Specific thresholds +- Timeline checkpoints + +### 6. Actual Results +Leave blank initially, fill in later: +- What actually happened? +- Which outcome occurred? +- Were assumptions valid? + +## Review Process + +After outcomes are known: +1. Compare predictions to reality +2. Identify where thinking was wrong +3. Extract lessons for future decisions + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/decision-journal/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/decision-journal/agents/openai.yaml new file mode 100644 index 0000000..0dd13af --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/decision-journal/agents/openai.yaml @@ -0,0 +1,5 @@ +name: decision-journal +description: Create structured records of decisions with expected outcomes, probabilities, and quit conditions. Use for important decisions. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/decision-reversibility/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/decision-reversibility/SKILL.md new file mode 100644 index 0000000..c429014 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/decision-reversibility/SKILL.md @@ -0,0 +1,58 @@ +--- +name: decision-reversibility +description: Classify decisions as Hat/Haircut/Tattoo by reversibility. Use to calibrate how much analysis a decision deserves. +--- + +# Decision Reversibility Classification + +Classify decisions by reversibility to calibrate how much analysis they deserve. + +## When to Use + +Before making a decision, to determine how much deliberation is warranted. + +## The Framework + +Classify decisions into three categories: + +| Type | Reversibility | Analysis Needed | +|------|---------------|-----------------| +| **Hat** | Easily reversible, minimal consequences | Decide quickly | +| **Haircut** | Reversible with effort/time | Moderate analysis | +| **Tattoo** | Largely irreversible, lasting impact | Deep analysis | + +## Analysis Criteria + +Consider these factors: + +1. **Immediate consequences** - What happens right away? +2. **Long-term effects** - On you, team, users, company? +3. **Reversal effort** - Time, money, resources to undo? +4. **Permanent changes** - What can't be undone? + +## Classification Guide + +**Hat (decide fast):** +- Can undo with minimal cost +- No lasting consequences +- Examples: Meeting time, doc format, tool choice + +**Haircut (moderate deliberation):** +- Reversible but requires time/effort +- Temporary discomfort if wrong +- Examples: Feature scope, team process, pricing test + +**Tattoo (deliberate carefully):** +- Largely permanent or very costly to reverse +- Long-lasting consequences +- Examples: Architecture choices, team structure, market positioning + +## Output + +- Decision classification (Hat/Haircut/Tattoo) +- Key factors driving the classification +- Recommended level of analysis + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/decision-reversibility/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/decision-reversibility/agents/openai.yaml new file mode 100644 index 0000000..c91e962 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/decision-reversibility/agents/openai.yaml @@ -0,0 +1,5 @@ +name: decision-reversibility +description: Classify decisions as Hat/Haircut/Tattoo by reversibility. Use to calibrate how much analysis a decision deserves. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/difficult-conversations/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/difficult-conversations/SKILL.md new file mode 100644 index 0000000..c4a24e0 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/difficult-conversations/SKILL.md @@ -0,0 +1,81 @@ +--- +name: difficult-conversations +description: Prepare for challenging conversations using Prepare-Listen-Empathize-Clarify-Solve framework. +--- + +# Difficult Conversation Prep + +Prepare for challenging work conversations using a structured framework. + +## When to Use + +Before any conversation you're dreading or that has conflict potential. + +## The Framework: Prepare-Listen-Empathize-Clarify-Solve + +### 1. Preparation Notes + +Document: +- Your intent (what you want to achieve) +- Non-negotiables (what you won't compromise on) +- Specific facts/examples (concrete, not accusations) +- Language traps to avoid +- Desired outcome +- Success criteria +- Medium choice (in-person/video/async) + +### 2. Opening Lines (3-5 options) + +Create openers that are: +- Neutral, non-accusatory +- Reference concrete impact +- Invite their perspective + +**Examples:** +- "I wanted to talk about [situation] because I've noticed [impact]..." +- "I'd like to understand your perspective on [issue]..." +- "Can we discuss [topic]? I want to make sure we're aligned..." + +### 3. Questions to Ask (5-7) + +Use open questions (what/how/when): +- Avoid "why" framing (feels accusatory) +- Include one perspective-taking question +- Include one constraints question + +### 4. Anticipate Reactions + +Prepare responses for: +- **Denial:** [De-escalating response] +- **Deflection:** [Redirect response] +- **Emotional reaction:** [Calming response] +- **Counter-accusation:** [Non-defensive response] + +### 5. Clarify and Solve + +- State shared goals +- Present options with trade-offs +- Agree on commitments +- Assign owner and timeline +- Schedule follow-up + +## Self-Management Checklist + +- [ ] Deep breaths before starting +- [ ] Slow speaking pace +- [ ] Use pauses deliberately +- [ ] Notice body tension +- [ ] Stay curious, not defensive + +## Output + +- 1-page prep doc +- Opening lines (3-5) +- Questions list +- Reactions/responses table +- Close and next steps +- Escalation flags (if HR/compliance needed) + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/difficult-conversations/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/difficult-conversations/agents/openai.yaml new file mode 100644 index 0000000..9129c07 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/difficult-conversations/agents/openai.yaml @@ -0,0 +1,5 @@ +name: difficult-conversations +description: Prepare for challenging conversations using Prepare-Listen-Empathize-Clarify-Solve framework. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/executive-update-review/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/executive-update-review/SKILL.md new file mode 100644 index 0000000..2632415 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/executive-update-review/SKILL.md @@ -0,0 +1,47 @@ +--- +name: executive-update-review +description: Improve executive updates for clarity, decision impact, and concise speaking flow. +--- + +# Executive Update Review + +Turn a draft update into a decision-ready executive communication. + +## Instructions + +### Step 1: Rewrite TLDR +- Exactly 3 bullets: what is wanted, why now, what changes. + +### Step 2: Diagnose issues and fixes +- Provide issue -> fix table. + +### Step 3: Rebuild narrative +- Hook, stakes, options with tradeoffs, recommendation, ask. + +### Step 4: Rewrite core section +- Plain language, <=200 words. + +### Step 5: Produce speaking notes +- Opening 15s, body 2m30s, close 15s. +- Include one story/data point, one risk, one clear ask. + +### Step 6: Improve slide economy +- Recommend cuts/merges. +- Provide one-slide executive summary layout. + +## Output + +- TLDR (3 bullets) +- Issue -> fix table +- Narrative structure +- Core rewrite +- 3-minute speaking notes +- Slide economy + one-slide layout + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/executive-update-review/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/executive-update-review/agents/openai.yaml new file mode 100644 index 0000000..00a02d1 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/executive-update-review/agents/openai.yaml @@ -0,0 +1,5 @@ +name: executive-update-review +description: Improve executive updates for clarity, decision impact, and concise speaking flow. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/experiment-design/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/experiment-design/SKILL.md new file mode 100644 index 0000000..7850790 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/experiment-design/SKILL.md @@ -0,0 +1,62 @@ +--- +name: experiment-design +description: Design robust experiments to test product hypotheses. Define metrics, sample size, and success criteria. +--- + +# Experiment Design + +Design robust experiments to test product hypotheses. + +## When to Use + +When you have a hypothesis and need to design an experiment to validate it. + +## The Process + +### 1. Factor Breakdown + +Analyze your goal and system: +- What factors could influence the outcome? +- Which are controllable vs. environmental? +- What are the key variables? + +### 2. Experiment Structure + +For each factor, define: +- **Hypothesis:** What you expect to happen +- **Independent variable:** What you're changing +- **Dependent variable:** What you're measuring +- **Control group:** Baseline comparison +- **Experimental group:** Who gets the change +- **Measurement method:** How you'll collect data +- **Confounding variables:** What else could affect results + +### 3. Sample Design +- Who participates? +- How many needed for statistical significance? +- How will you recruit/select? + +### 4. Timeline +- How long to run? +- When to check results? +- What's the minimum detectable effect? + +### 5. Stop/Scale Rules +- What results mean "stop"? +- What results mean "scale"? +- What's inconclusive? + +## Output Format + +For each experiment: +- Hypothesis statement +- Variables (independent, dependent) +- Groups (control, experimental) +- Sample size and selection +- Measurement approach +- Success criteria +- Stop/scale rules + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/experiment-design/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/experiment-design/agents/openai.yaml new file mode 100644 index 0000000..98915b1 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/experiment-design/agents/openai.yaml @@ -0,0 +1,5 @@ +name: experiment-design +description: Design robust experiments to test product hypotheses. Define metrics, sample size, and success criteria. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/frontend-design/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/frontend-design/SKILL.md new file mode 100644 index 0000000..07603d5 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/frontend-design/SKILL.md @@ -0,0 +1,91 @@ +--- +name: frontend-design +description: Design implementation-ready frontend solutions with UX intent, component structure, responsive behavior, accessibility, and handoff criteria. +--- + +# Frontend Design + +Use this skill to design frontend behavior and UI structure before or alongside implementation. + +## The Process + +### Step 1: Define UX objective + +Capture: +- user goal +- primary user flow +- success state and failure states + +### Step 2: Specify UI architecture + +Define: +- screen/layout structure +- component hierarchy +- state model (loading, empty, error, success) + +### Step 3: Specify design system decisions + +Set: +- typography and spacing rules +- color/contrast constraints +- interaction patterns + +### Step 4: Specify responsive and accessibility requirements + +Include: +- breakpoints and behavior changes +- keyboard navigation expectations +- ARIA/semantic requirements +- contrast and focus visibility requirements + +### Step 5: Define implementation handoff + +Provide: +- component list and props/state contract +- acceptance criteria +- verification checklist + +## Output Format + +```markdown +# [Feature Name] Frontend Design Spec + +## UX Objective +- User goal: +- Primary flow: +- Success/failure states: + +## UI Architecture +- Layout: +- Component hierarchy: +- State model: + +## Responsive Behavior +- Desktop: +- Tablet: +- Mobile: + +## Accessibility Requirements +- Keyboard: +- Semantics/ARIA: +- Contrast/focus: + +## Handoff +- Components to implement: +- Acceptance criteria: +- Verification checklist: +``` + +## Quality Bar + +- Design decisions must map to user goals +- Accessibility section is mandatory +- Handoff must be implementable without extra interpretation + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/frontend-design/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/frontend-design/agents/openai.yaml new file mode 100644 index 0000000..5d5d4e9 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/frontend-design/agents/openai.yaml @@ -0,0 +1,5 @@ +name: frontend-design +description: Design implementation-ready frontend solutions with UX intent, component structure, responsive behavior, accessibility, and handoff criteria. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/google-calendar-schedule-check/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/google-calendar-schedule-check/SKILL.md new file mode 100644 index 0000000..56b5210 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/google-calendar-schedule-check/SKILL.md @@ -0,0 +1,79 @@ +--- +name: google-calendar-schedule-check +description: Check Google Calendar for today's schedule. Use during daily planning or when user asks about their calendar. +--- + +# Calendar Schedule Check + +Check today's calendar and factor meetings into daily planning. + +## Instructions + +### Step 1: Fetch Today's Events + +Call `calendar_list_events` for today's date range. + +### Step 2: Categorize Events + +Group events by type: +- **Meetings** - Events with other attendees +- **Focus blocks** - Solo blocked time +- **External** - Events outside work calendar + +### Step 3: Calculate Available Time + +``` +Today's Schedule: + +09:00-10:00 Team standup (meeting) +11:00-12:00 1:1 with Sarah (meeting) +14:00-15:00 Focus time (blocked) + +Available for deep work: +- 10:00-11:00 (1 hour) +- 12:00-14:00 (2 hours) +- 15:00-17:00 (2 hours) + +Total: 5 hours available +``` + +### Step 4: Factor into Task Planning + +When recommending tasks: +- Match task estimated_time to available slots +- Prioritize P0/P1 tasks for longer blocks +- Suggest quick tasks for short gaps + +### Step 5: Offer Calendar Actions + +| Option | Description | +|--------|-------------| +| Block time | Reserve time for specific task | +| Reschedule | Move a meeting if needed | +| Continue | Proceed with task planning | + +## Example Flow + +**User:** "What should I work on today?" + +**Agent:** +1. Checks calendar +2. "You have 3 meetings today, 5 hours free..." +3. Shows schedule overview +4. Recommends tasks that fit available time +5. Offers to block time for priority tasks + +## Notes + +- Respect existing focus blocks +- Consider meeting prep time +- Account for lunch/breaks +- Warn if schedule is overloaded + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/google-calendar-schedule-check/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/google-calendar-schedule-check/agents/openai.yaml new file mode 100644 index 0000000..5d453ce --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/google-calendar-schedule-check/agents/openai.yaml @@ -0,0 +1,5 @@ +name: google-calendar-schedule-check +description: Check Google Calendar for today's schedule. Use during daily planning or when user asks about their calendar. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/granola-meeting-sync/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/granola-meeting-sync/SKILL.md new file mode 100644 index 0000000..6c076c9 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/granola-meeting-sync/SKILL.md @@ -0,0 +1,79 @@ +--- +name: granola-meeting-sync +description: Sync new Granola meetings to local Knowledge folder. Use during daily planning, when user asks "what should I do today", or asks to review/sync meetings. +--- + +# Meeting Sync + +Check for new Granola meetings and offer to sync them to your local Knowledge/transcripts folder. + +## Instructions + +### Step 1: Check for New Meetings + +Call the `check_new_meetings` tool via the Granola MCP to see unsynced meetings. + +### Step 2: Present Results + +If new meetings are found, present them to the user: + +``` +I found X new meeting(s) since your last sync: + +1. **Meeting Title** (Date) +2. **Meeting Title** (Date) +... + +Add to Knowledge folder? +``` + +### Step 3: Ask User for Selection + +Ask the user to choose one option: + +| Option | Description | +|--------|-------------| +| Sync all | Add all new meetings to Knowledge/transcripts | +| Select specific | Let user choose which meetings to sync | +| Skip for now | Continue without syncing | + +### Step 4: Sync Selected Meetings + +For each meeting the user wants to sync: +1. Call `sync_meeting_to_local` with the meeting ID +2. Confirm each sync completed + +### Step 5: Continue with Daily Flow + +After syncing (or skipping), continue with the normal daily planning workflow: +- Check tasks +- Review priorities +- Suggest focus items for the day + +## Example Flow + +**User:** "What should I do today?" + +**Agent:** +1. Calls `check_new_meetings` +2. "I found 3 new meetings since your last sync..." +3. Asks the user which meetings to sync +4. User selects "Sync all" or specific meetings +5. Syncs selected meetings +6. "Synced 3 meetings. Now for your day..." +7. Continues with task planning + +## Notes + +- Only Granola meetings with notes/content are worth syncing +- Meetings marked "(no notes)" may be empty placeholders +- Sync state is tracked in `Knowledge/.granola-sync.json` +- Files are saved to `Knowledge/transcripts/` with sanitized filenames + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/granola-meeting-sync/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/granola-meeting-sync/agents/openai.yaml new file mode 100644 index 0000000..5469ffc --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/granola-meeting-sync/agents/openai.yaml @@ -0,0 +1,5 @@ +name: granola-meeting-sync +description: Sync new Granola meetings to local Knowledge folder. Use during daily planning, when user asks "what should I do today", or asks to review/sync meetings. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/hidden-agendas/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/hidden-agendas/SKILL.md new file mode 100644 index 0000000..5254907 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/hidden-agendas/SKILL.md @@ -0,0 +1,71 @@ +--- +name: hidden-agendas +description: Identify potential hidden agendas of stakeholders. Use before high-stakes meetings with complex motivations. +--- + +# Hidden Agenda Analysis + +Identify potential hidden agendas of stakeholders before important meetings. + +## When to Use + +Before high-stakes meetings where stakeholder motivations may be complex. + +## Analysis Factors + +Consider for each stakeholder: + +**Official Position** +- Their stated role/stance + +**Potential Interests** +- Financial interests +- Power dynamics +- Reputation management +- Career advancement +- Ideological beliefs +- Personal relationships +- Organizational politics + +**Historical Context** +- Past behaviors +- Previous positions +- Track record + +**Relationships** +- Alliances with other stakeholders +- Conflicts or tensions +- Dependencies + +**Outcome Analysis** +- What do they gain from different outcomes? +- What do they lose? + +## The Process + +1. List all stakeholders involved +2. Document their official position +3. Analyze potential hidden motivations +4. Identify supporting factors for your analysis +5. Consider how agendas might interact or conflict + +## Output Format + +For each stakeholder: +- Name +- Official position +- Potential hidden agenda +- Supporting factors + +Plus: Overall situation summary showing how agendas interact. + +## Principles + +- Base analysis on provided information and reasonable inference +- Avoid unfounded speculation +- Consider multiple possibilities +- Stay objective and impartial + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/hidden-agendas/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/hidden-agendas/agents/openai.yaml new file mode 100644 index 0000000..6a5081a --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/hidden-agendas/agents/openai.yaml @@ -0,0 +1,5 @@ +name: hidden-agendas +description: Identify potential hidden agendas of stakeholders. Use before high-stakes meetings with complex motivations. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/hypothesis-design/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/hypothesis-design/SKILL.md new file mode 100644 index 0000000..64cdce6 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/hypothesis-design/SKILL.md @@ -0,0 +1,62 @@ +--- +name: hypothesis-design +description: Formulate clear, testable hypotheses for product experiments. Use when designing experiments to validate solutions. +--- + +# Product Hypothesis Design + +Formulate clear, testable hypotheses for product experiments. + +## When to Use + +When you have a product problem and need to design an experiment to validate a solution. + +## The Process + +### 1. Identify the Experiment Goal +- What user problem are you addressing? +- What change do you think will help? + +### 2. Draft Hypothesis Statement + +Use this structure: +``` +[Action] will cause [Outcome] to [Direction] for [Users] under [Conditions] +``` + +All 5 components required: +- **Action:** What you're doing +- **Outcome:** What metric changes +- **Direction:** Increase/decrease/improve +- **Users:** Who's affected +- **Conditions:** When/where this applies + +### 3. Check for Specificity +- Is the action clearly defined? +- Is the outcome measurable? +- Are users and conditions specific? + +### 4. Develop Measurement Plan +- What metrics prove success? +- How will you collect data? +- What's the sample size? + +### 5. Narrative Check + +Convert to story format: +``` +Currently, [user] is experiencing [problem]. +We believe that by [change], we'll see [outcome]. +We'll know we're right when [metric] changes by [amount]. +``` + +## Quality Check + +- Is the hypothesis falsifiable? +- Can you measure the outcome? +- Is the timeframe realistic? +- Are success criteria clear? + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/hypothesis-design/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/hypothesis-design/agents/openai.yaml new file mode 100644 index 0000000..458a903 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/hypothesis-design/agents/openai.yaml @@ -0,0 +1,5 @@ +name: hypothesis-design +description: Formulate clear, testable hypotheses for product experiments. Use when designing experiments to validate solutions. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/ideas-summary/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/ideas-summary/SKILL.md new file mode 100644 index 0000000..56156db --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/ideas-summary/SKILL.md @@ -0,0 +1,65 @@ +--- +name: ideas-summary +description: Summarize meetings using IDEAS framework - Insights, Decisions, Engagements, Actions, Summary. Use after any meeting. +--- + +# IDEAS Meeting Summary + +Summarize meetings using the IDEAS framework for clear, actionable notes. + +## When to Use + +After any meeting to create a structured summary. + +## The Framework + +**IDEAS = Insights, Decisions, Engagements, Actions, Summary** + +| Component | What to Capture | +|-----------|-----------------| +| **Insights** | Key realizations, important information surfaced | +| **Decisions** | Choices made during the meeting | +| **Engagements** | Tasks/responsibilities assigned to people | +| **Actions** | Immediate next steps needed | +| **Summary** | Overall impact and significance | + +## The Process + +1. Review the meeting transcript/notes +2. Extract items for each category +3. Use bullet points for clarity +4. Focus on most important points (not every detail) + +## Output Format + +``` +## Insights +- [Key realization 1] +- [Key realization 2] + +## Decisions +- [Decision made] +- [Decision made] + +## Engagements +- [Person]: [Responsibility assigned] +- [Person]: [Responsibility assigned] + +## Actions +- [Immediate action needed] +- [Immediate action needed] + +## Summary +[1-2 sentences on meeting's impact and significance] +``` + +## Quality Check + +- Are all decisions captured? +- Do engagements have clear owners? +- Are actions specific and immediate? +- Would someone who missed the meeting understand what happened? + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/ideas-summary/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/ideas-summary/agents/openai.yaml new file mode 100644 index 0000000..3d4a891 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/ideas-summary/agents/openai.yaml @@ -0,0 +1,5 @@ +name: ideas-summary +description: Summarize meetings using IDEAS framework - Insights, Decisions, Engagements, Actions, Summary. Use after any meeting. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/influence-strategies/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/influence-strategies/SKILL.md new file mode 100644 index 0000000..1e8636f --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/influence-strategies/SKILL.md @@ -0,0 +1,56 @@ +--- +name: influence-strategies +description: Generate influence strategies using Cialdini's seven principles. Use when you need to influence toward an outcome. +--- + +# Influence Strategies (Cialdini) + +Generate influence strategies using Cialdini's seven principles. + +## When to Use + +When you need to influence a stakeholder or group toward a specific outcome. + +## The Seven Principles + +| Principle | Core Idea | Application | +|-----------|-----------|-------------| +| **Reciprocity** | People return favors | Give first, then ask | +| **Liking** | People say yes to those they like | Build rapport, find common ground | +| **Unity** | Shared identity creates connection | Emphasize "we" and shared goals | +| **Authority** | People defer to experts | Demonstrate expertise, cite credible sources | +| **Social Proof** | People follow others | Show what peers/competitors do | +| **Consistency** | People honor commitments | Get small yeses before big asks | +| **Scarcity** | Limited = valuable | Highlight unique opportunity, deadlines | + +## The Process + +### 1. Define Your Context +- Who are you trying to influence? +- What outcome do you want? +- What's their current position? + +### 2. Generate Ideas for Each Principle + +For each of the seven, create at least one strategy: +- **Strategy:** What specifically to do +- **Rationale:** Why it works for this situation + +### 3. Select Best Approaches + +Prioritize strategies that: +- Fit the context naturally +- Are ethical and professional +- Create value for both parties +- Build long-term relationship + +## Principles + +- Focus on positive influence, not manipulation +- Create genuine value for both parties +- Maintain professional ethics +- Build relationships, not just transactions + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/influence-strategies/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/influence-strategies/agents/openai.yaml new file mode 100644 index 0000000..ac445be --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/influence-strategies/agents/openai.yaml @@ -0,0 +1,5 @@ +name: influence-strategies +description: Generate influence strategies using Cialdini's seven principles. Use when you need to influence toward an outcome. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/interview-cleanup/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/interview-cleanup/SKILL.md new file mode 100644 index 0000000..a8b10ab --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/interview-cleanup/SKILL.md @@ -0,0 +1,43 @@ +--- +name: interview-cleanup +description: Clean up raw interview transcripts while preserving meaning and speaker voice. Use after conducting interviews. +--- + +# Interview Transcript Cleanup + +Clean up raw interview transcripts while preserving meaning and speaker voice. + +## When to Use + +After conducting user interviews when you have raw transcripts that need cleanup before analysis. + +## The Process + +1. **Read the full transcript** to understand context and flow + +2. **Remove noise without losing meaning:** + - Filler words (um, uh, like, you know) + - False starts (incomplete/abandoned sentences) + - Redundancies (repeated words that don't add meaning) + +3. **Preserve what matters:** + - Original meaning and intent + - Speaker's unique voice and style + - Speaker labels (Interviewer:, Interviewee:) + - Unclear/inaudible markers [inaudible] + +4. **Light editing only:** + - Fix punctuation and capitalization + - Don't over-formalize casual language + - Don't cut unnecessarily + +## Quality Check + +- Does the cleaned transcript read naturally? +- Is the original meaning preserved? +- Can you still hear the speaker's voice? +- Are all speakers clearly labeled? + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/interview-cleanup/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/interview-cleanup/agents/openai.yaml new file mode 100644 index 0000000..64e0378 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/interview-cleanup/agents/openai.yaml @@ -0,0 +1,5 @@ +name: interview-cleanup +description: Clean up raw interview transcripts while preserving meaning and speaker voice. Use after conducting interviews. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/jtbd-clustering/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/jtbd-clustering/SKILL.md new file mode 100644 index 0000000..26a9976 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/jtbd-clustering/SKILL.md @@ -0,0 +1,45 @@ +--- +name: jtbd-clustering +description: Cluster forces from multiple JTBD interviews to identify patterns. Use after extracting from multiple interviews. +--- + +# JTBD Forces Clustering + +Cluster and categorize forces from multiple interviews for pattern analysis. + +## When to Use + +When you have JTBD extractions from multiple interviews and need to identify patterns across them. + +## The Process + +1. **Create a matrix:** + - Rows = interview stories + - Columns = distinct forces + +2. **Code each interview:** + - Start with first story's forces as initial columns + - For each new story: + - If force matches existing column: mark "1" + - If force is novel: add new column + +3. **Abstraction pass:** + - Review columns for grouping opportunities + - Rename with overarching descriptors + - Merge similar forces + +4. **Analysis questions:** + - Which forces appear most frequently? + - Which stories introduced unique forces? + - What patterns emerge across segments? + +## Output + +1. **Spreadsheet summary:** Number of stories and forces identified +2. **Force categories:** Abstract labels for each column +3. **Unique contributors:** Stories that introduced novel forces +4. **Patterns and insights:** Notable observations + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/jtbd-clustering/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/jtbd-clustering/agents/openai.yaml new file mode 100644 index 0000000..53251fe --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/jtbd-clustering/agents/openai.yaml @@ -0,0 +1,5 @@ +name: jtbd-clustering +description: Cluster forces from multiple JTBD interviews to identify patterns. Use after extracting from multiple interviews. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/jtbd-extraction/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/jtbd-extraction/SKILL.md new file mode 100644 index 0000000..30d595d --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/jtbd-extraction/SKILL.md @@ -0,0 +1,57 @@ +--- +name: jtbd-extraction +description: Analyze interviews using Jobs to Be Done framework. Extract push, pull, anxiety, and habit forces. +--- + +# JTBD Extraction from Interviews + +Analyze interview transcripts using the Jobs to Be Done framework to understand why people make changes. + +## When to Use + +When analyzing customer interviews to understand decision-making and switching behavior. + +## The Framework + +JTBD breaks decisions into four forces: + +| Force | What it captures | How to phrase | +|-------|------------------|---------------| +| **Pushes** | Pain with current situation | "When..." statements | +| **Pulls** | Desired outcomes | "So I can..." or "So I don't..." | +| **Habits** | Comfort with status quo | "When..." (positive aspects) | +| **Anxieties** | Fears about change | Questions or concerns | + +## The Process + +1. **Read the transcript** looking for moments of change or decision + +2. **Extract statements** for each force: + - Pushes: "When I'm not listened to..." + - Pulls: "So I can work with someone who trusts me..." + - Habits: "When I really like my current community..." + - Anxieties: "Can this really be fixed?" + +3. **Capture context:** + - Current situation + - Job/role + - Key challenges + +4. **Synthesize insights:** + - What's driving potential change? + - What's holding them back? + - What outcome do they really want? + +## Output Format + +Provide: +- Context summary +- Pushes (list) +- Pulls (list) +- Habits (list) +- Anxieties (list) +- Key insights about decision-making + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/jtbd-extraction/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/jtbd-extraction/agents/openai.yaml new file mode 100644 index 0000000..cca8859 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/jtbd-extraction/agents/openai.yaml @@ -0,0 +1,5 @@ +name: jtbd-extraction +description: Analyze interviews using Jobs to Be Done framework. Extract push, pull, anxiety, and habit forces. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/limit-based-strategy/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/limit-based-strategy/SKILL.md new file mode 100644 index 0000000..fc6ccd4 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/limit-based-strategy/SKILL.md @@ -0,0 +1,51 @@ +--- +name: limit-based-strategy +description: Develop a limit-based product strategy with convergence milestones, acceleration levers, assumptions, and phased execution. +--- + +# Limit-Based Strategy + +Use limit-based thinking to move from problem statement to execution plan. + +## Instructions + +### Step 1: Define growth variable and limit state +- Identify the primary growth variable. +- Describe the mature limit state clearly. + +### Step 2: Identify core properties +- List features and dynamics that must exist at the limit. + +### Step 3: Estimate convergence +- Provide milestones at 10%, 25%, 50%, 75%, and 90% with dates/triggers. + +### Step 4: Identify acceleration levers +- List levers to steepen convergence. +- Prioritize top 1-2 highest impact levers. + +### Step 5: List critical assumptions +- Capture assumptions and how each will be validated. + +### Step 6: Produce execution design +- One-sentence vision. +- Major roadmap milestones. +- 3-phase plan: Foundation, Acceleration, Optimization. +- Resource guidance. + +## Output + +- Growth variable +- Limit state +- Core properties +- Convergence estimate +- Acceleration strategies +- Critical assumptions + validation +- Vision and phased execution + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/limit-based-strategy/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/limit-based-strategy/agents/openai.yaml new file mode 100644 index 0000000..d4d4c5b --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/limit-based-strategy/agents/openai.yaml @@ -0,0 +1,5 @@ +name: limit-based-strategy +description: Develop a limit-based product strategy with convergence milestones, acceleration levers, assumptions, and phased execution. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/linear-issue-sync/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/linear-issue-sync/SKILL.md new file mode 100644 index 0000000..fac3d86 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/linear-issue-sync/SKILL.md @@ -0,0 +1,84 @@ +--- +name: linear-issue-sync +description: Sync Linear issues with local tasks. Use during daily planning or when user asks about Linear issues. +--- + +# Linear Issue Sync + +Check Linear for assigned issues and sync with local task management. + +## Instructions + +### Step 1: Fetch Assigned Issues + +Call `linear_list_issues` filtered to: +- Assigned to current user +- Status not "Done" or "Canceled" + +### Step 2: Compare with Local Tasks + +Check `Tasks/` for existing files with Linear references: +- Look for `linear_id` in YAML frontmatter +- Identify new issues not yet in Tasks/ + +### Step 3: Present Summary + +``` +Linear Issues (5 active): + +**High Priority** +- LIN-123: Fix authentication timeout [In Progress] +- LIN-124: Update API documentation [Todo] + +**Normal Priority** +- LIN-125: Refactor user service [Backlog] + +2 issues not yet in local Tasks. Create them? +``` + +### Step 4: Sync Options + +| Option | Description | +|--------|-------------| +| Create all | Add all new issues as local tasks | +| Select specific | Choose which to sync | +| Skip | Continue without syncing | + +### Step 5: Create Local Tasks + +For each issue to sync, create task file: + +```yaml +--- +title: [Issue title] +category: technical +priority: [Map from Linear priority] +status: n +linear_id: LIN-XXX +--- +``` + +## Example Flow + +**User:** "What should I work on today?" + +**Agent:** +1. Fetches Linear issues +2. Compares with local tasks +3. "You have 3 new Linear issues..." +4. Offers to create local tasks +5. Continues with planning + +## Notes + +- Map Linear priorities to P0-P3 +- Keep `linear_id` in frontmatter for bidirectional sync +- Update Linear status when local task completes + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/linear-issue-sync/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/linear-issue-sync/agents/openai.yaml new file mode 100644 index 0000000..878a4e3 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/linear-issue-sync/agents/openai.yaml @@ -0,0 +1,5 @@ +name: linear-issue-sync +description: Sync Linear issues with local tasks. Use during daily planning or when user asks about Linear issues. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/llm-coding-guardrails/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/llm-coding-guardrails/SKILL.md new file mode 100644 index 0000000..bbf5967 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/llm-coding-guardrails/SKILL.md @@ -0,0 +1,76 @@ +--- +name: llm-coding-guardrails +description: Behavioral guardrails to reduce common LLM coding mistakes with a caution-first approach. +--- + +# LLM Coding Guardrails + +Behavioral guidelines to reduce common LLM coding mistakes. + +Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +Do not assume. Do not hide confusion. Surface tradeoffs. + +Before implementing: +- State assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them. Do not pick silently. +- If a simpler approach exists, say so. +- If something is unclear, stop and ask. + +## 2. Simplicity First + +Write the minimum code that solves the problem. Nothing speculative. + +- No features beyond what was asked. +- No abstractions for single-use code. +- No configurability that was not requested. +- No error handling for impossible scenarios. +- If code is substantially longer than needed, simplify it. + +Quality check: +- Would a senior engineer call this overcomplicated? +- If yes, simplify. + +## 3. Surgical Changes + +Touch only what is necessary. Clean up only what your change affected. + +When editing existing code: +- Do not improve adjacent code, comments, or formatting unless required. +- Do not refactor unrelated working code. +- Match existing style unless asked to change it. +- If you notice unrelated dead code, mention it. Do not delete it. + +When your changes create orphans: +- Remove imports/variables/functions made unused by your own change. +- Do not remove pre-existing dead code unless asked. + +Test: +- Every changed line must map directly to the request. + +## 4. Goal-Driven Execution + +Define success criteria and iterate until verified. + +Turn requests into verifiable goals: +- "Add validation" -> "Write tests for invalid inputs, then make them pass" +- "Fix the bug" -> "Write a test that reproduces it, then make it pass" +- "Refactor X" -> "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan with checks: +1. [Step] -> verify: [check] +2. [Step] -> verify: [check] +3. [Step] -> verify: [check] + +Strong success criteria support independent iteration. +Weak criteria (for example, "make it work") require repeated clarification. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/llm-coding-guardrails/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/llm-coding-guardrails/agents/openai.yaml new file mode 100644 index 0000000..108bbfe --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/llm-coding-guardrails/agents/openai.yaml @@ -0,0 +1,5 @@ +name: llm-coding-guardrails +description: Behavioral guardrails to reduce common LLM coding mistakes with a caution-first approach. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/mece-analysis/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/mece-analysis/SKILL.md new file mode 100644 index 0000000..af7cd53 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/mece-analysis/SKILL.md @@ -0,0 +1,64 @@ +--- +name: mece-analysis +description: Structure thinking using Mutually Exclusive, Collectively Exhaustive categories. Use when breaking down problems or ensuring complete coverage. +--- + +# MECE Analysis + +Structure thinking using Mutually Exclusive, Collectively Exhaustive categories. + +## When to Use + +When you need to break down a problem, categorize options, or ensure complete coverage. + +## The Principle + +**MECE = Mutually Exclusive, Collectively Exhaustive** + +- **Mutually Exclusive:** No overlap between categories +- **Collectively Exhaustive:** All possibilities covered + +## The Process + +### 1. Analyze Mutual Exclusivity + +For each pair of items: +- Is there any overlap? +- Could something belong to both? +- If overlap exists, redefine boundaries + +### 2. Analyze Collective Exhaustiveness + +For the whole set: +- Are there gaps? +- What scenarios aren't covered? +- What's missing? + +### 3. Create Logical Tree + +Structure as hierarchy: +- Top level: Broadest categories +- Sub-levels: More specific breakdowns +- Each level should be MECE + +## Example + +**Bad (not MECE):** +- Marketing channels: Social, Digital, Facebook, Email +- (Facebook overlaps with Social and Digital) + +**Good (MECE):** +- Marketing channels: Paid, Owned, Earned + - Paid: Social ads, Search ads, Display + - Owned: Email, Website, App + - Earned: PR, Reviews, Word of mouth + +## Output + +- MECE categories with clear boundaries +- Logical tree showing hierarchy +- Notes on any gaps or overlaps found + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/mece-analysis/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/mece-analysis/agents/openai.yaml new file mode 100644 index 0000000..ff6107e --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/mece-analysis/agents/openai.yaml @@ -0,0 +1,5 @@ +name: mece-analysis +description: Structure thinking using Mutually Exclusive, Collectively Exhaustive categories. Use when breaking down problems or ensuring complete coverage. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/meeting-power-dynamics/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/meeting-power-dynamics/SKILL.md new file mode 100644 index 0000000..7485c1d --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/meeting-power-dynamics/SKILL.md @@ -0,0 +1,36 @@ +--- +name: meeting-power-dynamics +description: Map meeting-specific power dynamics, influence ranking, and tactical recommendations. +--- + +# Meeting Power Dynamics + +Analyze who influences outcomes in a specific meeting context. + +## Instructions + +### Step 1: Map influence +- Rank attendees by influence for this meeting. +- Separate formal authority and informal influence. + +### Step 2: Capture observations +- Identify alliances, conflict points, and imbalance risks. +- Note likely decision-makers and blockers. + +### Step 3: Recommend tactics +- Provide concrete strategies for navigating dynamics. +- Tie recommendations to specific attendees and situations. + +## Output + +- Power map with influence order and rationale +- Key observations +- Strategic recommendations + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/meeting-power-dynamics/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/meeting-power-dynamics/agents/openai.yaml new file mode 100644 index 0000000..a3f3eef --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/meeting-power-dynamics/agents/openai.yaml @@ -0,0 +1,5 @@ +name: meeting-power-dynamics +description: Map meeting-specific power dynamics, influence ranking, and tactical recommendations. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/message-framing-comms/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/message-framing-comms/SKILL.md new file mode 100644 index 0000000..fe1fa0f --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/message-framing-comms/SKILL.md @@ -0,0 +1,47 @@ +--- +name: message-framing-comms +description: Design audience-specific framing, drafts, and communication sequence for stakeholder updates. +--- + +# Message Framing And Comms + +Create concise, audience-aware messaging and rollout plan. + +## Instructions + +### Step 1: Generate framing options +- Provide 2-3 framing options. +- Include one-line rationale for each. + +### Step 2: Draft IC communication +- Subject/headline. +- Draft <=180 words. +- Slack announcement and reminder snippets. + +### Step 3: Draft executive communication +- Subject/headline. +- Draft <=120 words. +- Slack announcement and reminder snippets. + +### Step 4: Build mini comms plan +- Table: step, channel, owner, timing, emphasis, CTA. + +### Step 5: Noise reduction and success signals +- What to omit list. +- Exactly 3 measurable success signals. + +## Output + +- Frames and rationale +- IC draft + snippets +- Executive draft + snippets +- Mini comms plan +- Omit list + 3 success signals + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/message-framing-comms/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/message-framing-comms/agents/openai.yaml new file mode 100644 index 0000000..8a34b09 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/message-framing-comms/agents/openai.yaml @@ -0,0 +1,5 @@ +name: message-framing-comms +description: Design audience-specific framing, drafts, and communication sequence for stakeholder updates. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/opportunity-solution-tree/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/opportunity-solution-tree/SKILL.md new file mode 100644 index 0000000..24143aa --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/opportunity-solution-tree/SKILL.md @@ -0,0 +1,87 @@ +--- +name: opportunity-solution-tree +description: Transform research into Opportunity Solution Tree (Teresa Torres method). Map outcomes, opportunities, solutions, and experiments. +--- + +# Opportunity Solution Tree (OST) + +Transform interview data into a structured Opportunity Solution Tree following Teresa Torres's method. + +## When to Use + +When synthesizing user research into a structured view of opportunities. + +## Key Concepts + +**Opportunity:** A customer need, pain, or desire - phrased from user perspective, not a solution. + +**Moment in time:** A distinct point in the customer journey. + +**Tests:** +- **Distinctness (siblings):** Can we pursue one without addressing the other? If yes, they're distinct. +- **Parent-child:** Does solving the child partially solve the parent? If not, reframe. + +## The Process + +### 1. Extract Opportunities + +From interviews, capture: +- Verbatim quotes +- Reframed user-need statement +- Which journey moment it belongs to + +### 2. Organize by Journey Moments + +Group opportunities under their primary moment in time. + +### 3. Structure Within Each Moment + +- Cluster similar opportunities +- Create parent nodes where needed +- Run distinctness checks across siblings +- Run parent-child checks down branches +- Remove generic parents with single children +- Combine near-duplicates + +### 4. Track Evidence + +For each opportunity, capture: +- Representative quotes +- Frequency count +- Confidence level (low/med/high) + +### 5. Prioritize Leaves + +Score leaf opportunities: +- Impact (1-5) +- Frequency (1-5) +- Alignment to outcome (1-5) +- Priority = Impact x Frequency x Alignment + +## Output Format + +**Opportunity Inventory Table:** +| ID | Moment | Opportunity | Parent ID | Quotes | Frequency | Confidence | + +**Tree View (per moment):** +``` +## [Moment Name] +- [Parent opportunity] + - [Child opportunity] + - [Grandchild] +``` + +**Prioritized Leaf Backlog:** +Ranked list with scores and rationale. + +## Rules + +- All opportunities from user perspective +- No solutions in the tree +- Keep distinct across siblings +- Prefer specific over generic +- Preserve verbatim quotes for evidence + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/opportunity-solution-tree/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/opportunity-solution-tree/agents/openai.yaml new file mode 100644 index 0000000..0820e6c --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/opportunity-solution-tree/agents/openai.yaml @@ -0,0 +1,5 @@ +name: opportunity-solution-tree +description: Transform research into Opportunity Solution Tree (Teresa Torres method). Map outcomes, opportunities, solutions, and experiments. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/ost-intake/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/ost-intake/SKILL.md new file mode 100644 index 0000000..66338b1 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/ost-intake/SKILL.md @@ -0,0 +1,40 @@ +--- +name: ost-intake +description: Normalize and collect complete Opportunity Solution Tree inputs before OST synthesis. +--- + +# OST Intake + +Collect high-quality, normalized inputs for OST work. + +## Instructions + +### Step 1: Parse existing context first +- Use provided context before asking questions. + +### Step 2: Collect four required fields +- `business_outcome` +- `journey_nodes_as_list` (JSON array of moments) +- `interview_transcripts_or_story_snippets` +- `constraints_or_principles` (or `None stated`) + +### Step 3: Normalize quality +- Reframe solution-flavored outcomes into measurable outcomes. +- Reframe feature-like nodes into moments in time. +- Add minimal attribution to transcript snippets when possible. + +### Step 4: Ask only missing critical questions +- Ask concise questions only for missing required inputs. +- Stop when all four fields are complete and clear. + +## Output + +- Final normalized values for all four required fields. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/ost-intake/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/ost-intake/agents/openai.yaml new file mode 100644 index 0000000..5b06adb --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/ost-intake/agents/openai.yaml @@ -0,0 +1,5 @@ +name: ost-intake +description: Normalize and collect complete Opportunity Solution Tree inputs before OST synthesis. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/ost-target-selection/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/ost-target-selection/SKILL.md new file mode 100644 index 0000000..209e7db --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/ost-target-selection/SKILL.md @@ -0,0 +1,47 @@ +--- +name: ost-target-selection +description: Select one target opportunity from an OST using evidence-based weighted scoring and tie-breakers. +--- + +# OST Target Selection + +Choose exactly one opportunity to pursue next. + +## Instructions + +### Step 1: Harvest candidates from OST +- Include leaves and relevant parents with strong evidence. +- Merge duplicates and reframe solution language into need language. + +### Step 2: Score candidates +- Score 1-5 for OS, MF, CF, CuF. +- Use default weights unless custom weights are provided. +- Compute weighted priority score (WPS). + +### Step 3: Build shortlist +- Select top 3-5 by WPS. +- Apply tie-breakers: distinctness, evidence quality, time-to-learning, risk diversification. + +### Step 4: Recommend one target +- Pick one small, distinct, moment-scoped opportunity. +- Exclude engineering effort prioritization. + +### Step 5: Audit alignment +- Confirm no-effort-policy and moment distinctness. +- List evidence gaps and follow-up needs. + +## Output + +- Candidate inventory +- Scoring matrix with WPS +- Top 3-5 shortlist +- Single recommendation with rationale +- Audit notes + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/ost-target-selection/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/ost-target-selection/agents/openai.yaml new file mode 100644 index 0000000..b483998 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/ost-target-selection/agents/openai.yaml @@ -0,0 +1,5 @@ +name: ost-target-selection +description: Select one target opportunity from an OST using evidence-based weighted scoring and tie-breakers. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/power-map/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/power-map/SKILL.md new file mode 100644 index 0000000..462056d --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/power-map/SKILL.md @@ -0,0 +1,80 @@ +--- +name: power-map +description: Map stakeholders by power and interest to plan engagement strategy. Use when starting multi-stakeholder initiatives. +--- + +# Stakeholder Power-Interest Map + +Map stakeholders by power and interest to plan engagement strategy. + +## When to Use + +When starting an initiative that involves multiple stakeholders. + +## The Framework + +### Power-Interest Grid + +| | Low Interest | High Interest | +|---|---|---| +| **High Power** | Keep Satisfied | Manage Closely | +| **Low Power** | Monitor | Keep Informed | + +### Influence Pyramid + +Beyond formal power, map informal influence: +- **Top tier:** Decision makers, budget holders +- **Middle tier:** Gatekeepers, team leads +- **Base tier:** Super-connectors, exec assistants + +## The Process + +### 1. List Stakeholders + +Gather: +- Names and roles +- Organizational position +- Known relationships +- Allies and blockers + +### 2. Map to Grid + +Place each stakeholder in the 2x2 based on: +- **Power:** Formal authority, budget control, veto ability +- **Interest:** How much they care about this initiative + +### 3. Build Influence Pyramid + +Identify informal power: +- Who controls access? +- Who influences opinion? +- Who connects people? + +### 4. Profile High-Power Stakeholders + +For each, document: +- Goals and success metrics +- Likely concerns (political, operational, reputational) +- Preferred communication style +- Political risks for you + +### 5. Create Engagement Plan + +For each high-power stakeholder: +- Cadence and channel +- Format and owner +- Key message (tied to their priorities) +- Quick win to offer +- Fallback if they resist + +## Output + +- Power-Interest matrix with names +- Influence pyramid with rationale +- High-power profiles table +- Engagement plan table +- Top 3 political pitfalls to avoid + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/power-map/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/power-map/agents/openai.yaml new file mode 100644 index 0000000..c9b453c --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/power-map/agents/openai.yaml @@ -0,0 +1,5 @@ +name: power-map +description: Map stakeholders by power and interest to plan engagement strategy. Use when starting multi-stakeholder initiatives. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/prd-writing/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/prd-writing/SKILL.md new file mode 100644 index 0000000..7e91127 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/prd-writing/SKILL.md @@ -0,0 +1,120 @@ +--- +name: prd-writing +description: Write a structured PRD for high-risk, cross-team, or multi-sprint initiatives before implementation. +--- + +# PRD Writing + +Create clear, implementation-ready product requirements documents for initiatives that need alignment before coding. + +## The Process + +### Step 1: Confirm PRD is needed + +Use PRD only if at least one is true: +- cross-team dependency +- multi-sprint scope +- high-risk decision or expensive tradeoff +- stakeholder alignment needed before build + +If none apply, recommend execution-first flow (`writing-plans` -> `tdd` -> `verification`) instead. + +### Step 2: Gather required inputs + +Collect: +- product goal and target user +- business context and constraints +- known assumptions and risks +- success criteria and timeline + +State explicit assumptions when inputs are missing. + +### Step 3: Produce PRD in required format + +Use this exact structure: + +```markdown +# [Product Name] + +## About +[High-level overview of the product and goal.] + +## Market Insights +[Market context, competitors, trends, and target users.] + +## Problem +[Core user problem, pain points, and why existing solutions are insufficient.] + +## Solution +[Proposed AI product solution and how it addresses the problem.] + +## Feature Prioritization + +| Feature | Reach | Impact | Confidence | Effort | RICE Score | Priority | +|---------|-------|--------|------------|--------|------------|----------| +| | | | | | | | +| | | | | | | | +| | | | | | | | + +## Requirements + +**Functional Requirements:** +- FR1: +- FR2: +- FR3: + +**AI/ML Model Requirements:** +- MR1: +- MR2: +- MR3: + +**Non-Functional Requirements:** +- NFR1: +- NFR2: +- NFR3: + +## Challenges +[Key product, technical, data, and go-to-market challenges.] + +## Positioning + +| Use Case | Target User | Key Benefit | Differentiator | +|----------|-------------|-------------|----------------| +| | | | | +| | | | | +| | | | | + +## Metrics +[Success metrics and north star metric.] + +## Rollout Plan + +- **Stakeholders & Communication** + - [Stakeholder groups and communication plan] + +- **Roll-out Strategy** + - [Launch phases, gating criteria, and post-GA plan] +``` + +### Step 4: Quality checks before finalizing + +Ensure: +- no placeholder fields remain +- RICE rows are populated and prioritized +- metrics include baseline, target, and timeframe +- rollout includes phases and gating criteria +- top risks are explicit + +## Output + +- Final PRD in the required structure +- A short assumptions list +- Open questions/blockers list + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/prd-writing/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/prd-writing/agents/openai.yaml new file mode 100644 index 0000000..5080ff1 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/prd-writing/agents/openai.yaml @@ -0,0 +1,5 @@ +name: prd-writing +description: Write a structured PRD for high-risk, cross-team, or multi-sprint initiatives before implementation. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/problem-structuring/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/problem-structuring/SKILL.md new file mode 100644 index 0000000..fd22a4d --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/problem-structuring/SKILL.md @@ -0,0 +1,61 @@ +--- +name: problem-structuring +description: Break down complex problems into actionable recommendations using deductive and inductive analysis. +--- + +# Problem Structuring + +Break down complex problems into actionable recommendations. + +## When to Use + +When facing a complex, ambiguous problem that needs structured analysis. + +## The Process + +### 1. Simplify the Problem + +- Identify core components +- List key stakeholders +- Summarize in 2-3 sentences + +### 2. Deductive Analysis (Top-Down) + +Start broad, work to specifics: +- What's the general situation? +- Create logical tree of options +- Map cause-and-effect relationships +- Explore branches and outcomes + +### 3. Inductive Analysis (Bottom-Up) + +Start with specifics, find patterns: +- Examine data points and examples +- Look for patterns and trends +- What do specifics suggest about the whole? + +### 4. Synthesize + +Combine both approaches: +- Where do they agree? +- Where do they conflict? +- What insights emerge? + +### 5. Develop Recommendation + +Based on analysis: +- Clear, actionable recommendation +- Rationale tied to analysis +- Trade-offs acknowledged + +## Output Format + +- **Simplified problem:** Concise summary +- **Deductive analysis:** Logical tree with options +- **Inductive analysis:** Patterns from data +- **Synthesis:** Combined insights +- **Recommendation:** Clear action with rationale + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/problem-structuring/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/problem-structuring/agents/openai.yaml new file mode 100644 index 0000000..e011662 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/problem-structuring/agents/openai.yaml @@ -0,0 +1,5 @@ +name: problem-structuring +description: Break down complex problems into actionable recommendations using deductive and inductive analysis. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/root-cause-analysis/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/root-cause-analysis/SKILL.md new file mode 100644 index 0000000..277bc14 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/root-cause-analysis/SKILL.md @@ -0,0 +1,55 @@ +--- +name: root-cause-analysis +description: Uncover root causes through recursive Why questioning and consequence exploration. Use before acting on problems. +--- + +# Root Cause Analysis + +Uncover root causes and explore consequences through structured questioning. + +## When to Use + +When you need to deeply understand a problem, decision, or situation before acting. + +## The Process + +### 1. Recursive "Why" Questioning + +Start with the initial question and ask "Why?" repeatedly: +- Ask "Why?" at least 5 times +- Go deeper until you reach fundamental causes +- If multiple reasons emerge, explore each branch + +**Example:** +- Why did users churn? → Onboarding was confusing +- Why was it confusing? → Too many steps +- Why too many steps? → We added features without simplifying +- Why didn't we simplify? → No ownership of onboarding experience +- Why no ownership? → Org structure doesn't align to user journey + +### 2. Consequence Exploration + +After finding root causes, explore forward: +- **1st order:** Immediate consequences +- **2nd order:** What results from those? +- **3rd-5th order:** Downstream effects + +Consider both positive and negative outcomes. + +### 3. First Principles Check + +- What fundamental truths underlie this? +- What assumptions are we making? +- What alternative perspectives exist? +- Where are the gaps in logic? + +## Output Format + +- Root causes (the "Why?" chain) +- Consequences (1st through 5th order) +- First principles (fundamental truths, assumptions) +- Conclusion (key insights) + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/root-cause-analysis/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/root-cause-analysis/agents/openai.yaml new file mode 100644 index 0000000..adbdf71 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/root-cause-analysis/agents/openai.yaml @@ -0,0 +1,5 @@ +name: root-cause-analysis +description: Uncover root causes through recursive Why questioning and consequence exploration. Use before acting on problems. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/signal-identification/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/signal-identification/SKILL.md new file mode 100644 index 0000000..a089906 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/signal-identification/SKILL.md @@ -0,0 +1,66 @@ +--- +name: signal-identification +description: Design efficient early signals to validate assumptions. Find the fastest way to learn if you're right. +--- + +# Signal Identification + +Design efficient early signals to validate product assumptions. + +## When to Use + +When you have a prioritized assumption and need the fastest way to validate it. + +## The Quality Bar + +A good signal is: +- **Early:** Obtainable at idea/prototype stage +- **Cheap:** Minimal cash/time +- **Attributable:** Directly reduces uncertainty +- **Decisive:** Has clear success/failure threshold +- **Suitable:** Appropriate for your context + +## Method Selection by Context + +| Context | Good Methods | Avoid | +|---------|--------------|-------| +| **Enterprise B2B** | Design partner LOIs, security questionnaires, ROI calculators, reference checks | Smoke tests, consumer ad funnels | +| **SMB SaaS** | Discovery calls, lightweight trials, email tests, usage analytics | - | +| **Consumer** | Ad-driven intent, waitlist conversion, community polls, preorders | - | +| **Regulated** | Standards mapping, SME review, regulatory preflight | Collecting sensitive data | +| **Feasibility** | Engineering spikes, benchmarks, vendor evals | User-facing experiments | + +## The Process + +### 1. Classify the Assumption + +What lens? Desirability, Feasibility, Viability, or Usability? + +### 2. Brainstorm Signals (5+) + +For each, note: +- What would constitute positive evidence? +- How to obtain quickly? +- Why suitable for this context? + +### 3. Select Best Signal + +Document: +- Signal description +- Method (step-by-step) +- Participants/sample needed +- Timebox and cost +- Success threshold (quantified) +- Data captured +- Risks and mitigations +- What to do next if positive + +## Output + +- Brainstorm list (5+ signals) +- Selected signal with full details +- Summary explaining choice + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/signal-identification/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/signal-identification/agents/openai.yaml new file mode 100644 index 0000000..2552a21 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/signal-identification/agents/openai.yaml @@ -0,0 +1,5 @@ +name: signal-identification +description: Design efficient early signals to validate assumptions. Find the fastest way to learn if you're right. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/slack-message-check/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/slack-message-check/SKILL.md new file mode 100644 index 0000000..91db25b --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/slack-message-check/SKILL.md @@ -0,0 +1,75 @@ +--- +name: slack-message-check +description: Check Slack for important messages and activity. Use during daily planning or when user asks about Slack updates. +--- + +# Slack Message Check + +Check Slack channels for important messages and summarize activity. + +## Instructions + +### Step 1: List Relevant Channels + +Call `slack_list_channels` to see available channels. + +### Step 2: Check Priority Channels + +For each important channel (determined by user preferences or channel activity): +1. Call `slack_get_channel_history` with limit of 20 messages +2. Filter for messages since last check + +### Step 3: Summarize Activity + +Present findings to user: + +``` +Slack activity since yesterday: + +**#general** (3 new messages) +- @alice mentioned the deployment schedule + +**#engineering** (12 new messages) +- Discussion about API changes +- @bob asked for review on PR #234 + +**DMs** (2 unread) +- @carol: Question about meeting time +``` + +### Step 4: Offer Actions + +| Option | Description | +|--------|-------------| +| Create task | Turn a message into a task | +| Reply | Draft a response | +| Mark read | Continue without action | + +### Step 5: Continue Daily Flow + +After Slack check, continue with normal planning workflow. + +## Example Flow + +**User:** "What should I work on today?" + +**Agent:** +1. Checks Slack for new activity +2. "You have 5 new messages across 2 channels..." +3. Summarizes key items +4. Offers to create tasks from actionable messages +5. Continues with task planning + +## Notes + +- Focus on actionable messages, not all activity +- Prioritize DMs and mentions over general channel noise +- Respect user's channel preferences if configured + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/slack-message-check/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/slack-message-check/agents/openai.yaml new file mode 100644 index 0000000..986e724 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/slack-message-check/agents/openai.yaml @@ -0,0 +1,5 @@ +name: slack-message-check +description: Check Slack for important messages and activity. Use during daily planning or when user asks about Slack updates. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/spec-writing/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/spec-writing/SKILL.md new file mode 100644 index 0000000..3953ce1 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/spec-writing/SKILL.md @@ -0,0 +1,93 @@ +--- +name: spec-writing +description: Convert an approved PRD or clear requirements into an implementation-ready technical spec with scope, interfaces, and acceptance criteria. +--- + +# Spec Writing + +Use this skill to produce an implementation-ready spec before planning or coding. + +## The Process + +### Step 1: Validate inputs + +Require one of: +- approved PRD +- clear requirements with goals and constraints + +If inputs are missing or ambiguous, list assumptions and open questions first. + +### Step 2: Define scope boundaries + +Document: +- in scope +- out of scope +- constraints (time, dependencies, compliance, platform) + +### Step 3: Define solution design + +Specify: +- architecture overview (high-level components) +- interfaces/contracts +- data model changes +- rollout and migration approach + +### Step 4: Define acceptance and verification + +Include: +- acceptance criteria (testable) +- non-functional expectations (performance, security, reliability) +- verification commands/checks required before completion + +## Output Format + +```markdown +# [Feature Name] Technical Spec + +## Goal +[What this spec delivers and why] + +## Scope +- In scope: +- Out of scope: +- Constraints: + +## Design +- Architecture: +- Interfaces/contracts: +- Data model changes: +- Migration/rollout: + +## Risks and Dependencies +- Risks: +- Dependencies: +- Mitigations: + +## Acceptance Criteria +- AC1: +- AC2: +- AC3: + +## Verification Plan +- Required checks: +- Commands: +- Evidence to capture: + +## Open Questions +- Q1: +- Q2: +``` + +## Quality Bar + +- No vague placeholders in final output +- Acceptance criteria must be measurable +- Verification plan must include explicit commands + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/spec-writing/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/spec-writing/agents/openai.yaml new file mode 100644 index 0000000..36a3847 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/spec-writing/agents/openai.yaml @@ -0,0 +1,5 @@ +name: spec-writing +description: Convert an approved PRD or clear requirements into an implementation-ready technical spec with scope, interfaces, and acceptance criteria. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/stakeholder-risk-review/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/stakeholder-risk-review/SKILL.md new file mode 100644 index 0000000..107147f --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/stakeholder-risk-review/SKILL.md @@ -0,0 +1,47 @@ +--- +name: stakeholder-risk-review +description: Review a feature or PRD for stakeholder and political risk before broad circulation. +--- + +# Stakeholder Risk Review + +Stress-test a proposal for adoption and political risk. + +## Instructions + +### Step 1: Build snapshot +- Create power-interest matrix with named stakeholders. +- Include informal influencers. + +### Step 2: Map concerns +- For each key stakeholder: concern, evidence needed, response plan. + +### Step 3: Define mitigation plan +- Document improvements and 1:1 messaging by stakeholder. +- Provide exactly 3 pre-work actions. + +### Step 4: Define framing and sequence +- Provide separate framing for executives and ICs. +- Provide minimal communication sequence. + +### Step 5: Capture risks and readiness +- Risk table with mitigation + owner. +- Readiness checklist. + +## Output + +- Power-interest snapshot +- Stakeholder concerns table +- Document changes +- 1:1 messages +- Top 3 pre-work actions +- Framing + comms sequence +- Risks + readiness checklist + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/stakeholder-risk-review/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/stakeholder-risk-review/agents/openai.yaml new file mode 100644 index 0000000..a9caa24 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/stakeholder-risk-review/agents/openai.yaml @@ -0,0 +1,5 @@ +name: stakeholder-risk-review +description: Review a feature or PRD for stakeholder and political risk before broad circulation. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/structured-product-strategy/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/structured-product-strategy/SKILL.md new file mode 100644 index 0000000..f61cf5f --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/structured-product-strategy/SKILL.md @@ -0,0 +1,54 @@ +--- +name: structured-product-strategy +description: Build a complete product strategy from context, including objective, users, superpowers, vision, pillars, impact, and roadmap. +--- + +# Structured Product Strategy + +Create a coherent strategy from product context. + +## Instructions + +### Step 1: Define objective +- Write a 1-2 sentence objective that is ambitious and achievable. + +### Step 2: Define users and needs +- Choose 1-2 core user groups. +- List 3-4 concrete needs for each. + +### Step 3: Identify superpowers +- Name 3-4 unique advantages that can compound. + +### Step 4: Draft vision +- Write 2-3 paragraphs linking objective, users, and superpowers. + +### Step 5: Define pillars and impact +- Create 2-4 strategy pillars. +- Explain causal impact mechanism to business outcomes. + +### Step 6: Draft roadmap by pillar +- Provide 3-10 initiatives per pillar. +- Do not prioritize unless asked. + +## Output + +- Objective +- Users +- Superpowers +- Vision +- Pillars +- Impact mechanism +- Roadmap by pillar + +## Quality Bar + +- Ground every claim in provided context. +- State assumptions explicitly when context is missing. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/structured-product-strategy/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/structured-product-strategy/agents/openai.yaml new file mode 100644 index 0000000..eb50361 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/structured-product-strategy/agents/openai.yaml @@ -0,0 +1,5 @@ +name: structured-product-strategy +description: Build a complete product strategy from context, including objective, users, superpowers, vision, pillars, impact, and roadmap. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/systematic-debugging/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/systematic-debugging/SKILL.md new file mode 100644 index 0000000..539d063 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/systematic-debugging/SKILL.md @@ -0,0 +1,115 @@ +--- +name: systematic-debugging +description: Four-phase debugging process - root cause first, then fix. Use when encountering bugs or unexpected behavior. +--- + +# Systematic Debugging + +Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. + +## The Iron Law + +``` +NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST +``` + +If you haven't completed Phase 1, you cannot propose fixes. + +## The Four Phases + +### Phase 1: Root Cause Investigation + +**BEFORE attempting ANY fix:** + +1. **Read Error Messages Carefully** + - Don't skip past errors or warnings + - Read stack traces completely + - Note line numbers, file paths, error codes + +2. **Reproduce Consistently** + - Can you trigger it reliably? + - What are the exact steps? + - If not reproducible, gather more data + +3. **Check Recent Changes** + - Git diff, recent commits + - New dependencies, config changes + - Environmental differences + +4. **Trace Data Flow** + - Where does bad value originate? + - What called this with bad value? + - Keep tracing up until you find the source + +### Phase 2: Pattern Analysis + +1. **Find Working Examples** + - Locate similar working code in same codebase + +2. **Compare Against References** + - Read reference implementation completely + - Don't skim - read every line + +3. **Identify Differences** + - What's different between working and broken? + - List every difference, however small + +### Phase 3: Hypothesis and Testing + +1. **Form Single Hypothesis** + - State clearly: "I think X is the root cause because Y" + - Write it down + +2. **Test Minimally** + - Make the SMALLEST possible change + - One variable at a time + +3. **Verify Before Continuing** + - Did it work? Yes -> Phase 4 + - Didn't work? Form NEW hypothesis + - DON'T add more fixes on top + +### Phase 4: Implementation + +1. **Create Failing Test Case** + - Use the `tdd.md` skill + +2. **Implement Single Fix** + - ONE change at a time + - No "while I'm here" improvements + +3. **Verify Fix** + - Test passes now? + - No other tests broken? + +4. **If 3+ Fixes Failed: Question Architecture** + - Is this pattern fundamentally sound? + - Should we refactor vs continue fixing symptoms? + - Discuss before attempting more fixes + +## Red Flags - STOP and Follow Process + +- "Quick fix for now, investigate later" +- "Just try changing X and see if it works" +- "I don't fully understand but this might work" +- Proposing solutions before tracing data flow +- "One more fix attempt" (when already tried 2+) + +**ALL mean: STOP. Return to Phase 1.** + +## Quick Reference + +| Phase | Key Activities | Success Criteria | +|-------|---------------|------------------| +| 1. Root Cause | Read errors, reproduce, check changes | Understand WHAT and WHY | +| 2. Pattern | Find working examples, compare | Identify differences | +| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis | +| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass | + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/systematic-debugging/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/systematic-debugging/agents/openai.yaml new file mode 100644 index 0000000..6200c34 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/systematic-debugging/agents/openai.yaml @@ -0,0 +1,5 @@ +name: systematic-debugging +description: Four-phase debugging process - root cause first, then fix. Use when encountering bugs or unexpected behavior. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/tdd/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/tdd/SKILL.md new file mode 100644 index 0000000..8deb167 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/tdd/SKILL.md @@ -0,0 +1,105 @@ +--- +name: tdd +description: Test-driven development - write failing test first, then minimal code. Use before implementing any feature or bugfix. +--- + +# Test-Driven Development (TDD) + +Use when implementing any feature or bugfix, before writing implementation code. + +## The Iron Law + +``` +NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST +``` + +Write code before the test? Delete it. Start over. + +**No exceptions:** +- Don't keep it as "reference" +- Don't "adapt" it while writing tests +- Delete means delete + +## Red-Green-Refactor + +### RED - Write Failing Test +Write one minimal test showing what should happen. +- One behavior +- Clear name +- Real code (no mocks unless unavoidable) + +### Verify RED - Watch It Fail +**MANDATORY. Never skip.** +- Run the test, confirm it fails (not errors) +- Failure message is expected +- Test passes? You're testing existing behavior. Fix test. + +### GREEN - Minimal Code +Write simplest code to pass the test. +- Just enough to pass +- No extra features +- Don't add behavior beyond the test + +### Verify GREEN - Watch It Pass +**MANDATORY.** +- Test passes +- Other tests still pass +- Output pristine (no errors, warnings) + +### REFACTOR - Clean Up +After green only: +- Remove duplication +- Improve names +- Extract helpers +Keep tests green. Don't add behavior. + +## Why Order Matters + +**"I'll write tests after"** +Tests written after pass immediately. Passing immediately proves nothing. Test-first forces you to see the test fail, proving it actually tests something. + +**"Tests after achieve same goals"** +No. Tests-after answer "What does this do?" Tests-first answer "What should this do?" + +**"Deleting X hours of work is wasteful"** +Sunk cost fallacy. The time is gone. The waste is keeping code you can't trust. + +## Red Flags - STOP and Start Over + +- Code before test +- Test after implementation +- Test passes immediately +- "I already manually tested it" +- "Tests after achieve the same purpose" +- "This is different because..." + +**All mean: Delete code. Start over with TDD.** + +## Common Rationalizations + +| Excuse | Reality | +|--------|---------| +| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | +| "I'll test after" | Tests passing immediately prove nothing. | +| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. | +| "TDD will slow me down" | TDD faster than debugging later. | + +## Verification Checklist + +Before marking work complete: +- [ ] Every new function/method has a test +- [ ] Watched each test fail before implementing +- [ ] Each test failed for expected reason +- [ ] Wrote minimal code to pass each test +- [ ] All tests pass +- [ ] Output pristine (no errors, warnings) + +Can't check all boxes? You skipped TDD. Start over. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/tdd/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/tdd/agents/openai.yaml new file mode 100644 index 0000000..01bd376 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/tdd/agents/openai.yaml @@ -0,0 +1,5 @@ +name: tdd +description: Test-driven development - write failing test first, then minimal code. Use before implementing any feature or bugfix. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/value-chain-mapping/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/value-chain-mapping/SKILL.md new file mode 100644 index 0000000..10699d5 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/value-chain-mapping/SKILL.md @@ -0,0 +1,38 @@ +--- +name: value-chain-mapping +description: Map end-user needs to the full value chain, identify core value generators, and highlight vulnerabilities. +--- + +# Value Chain Mapping + +Map value creation from user needs to foundational inputs. + +## Instructions + +### Step 1: Capture end-user needs +- List primary user needs the product serves. + +### Step 2: Build value chain hierarchy +- Trace from needs -> activities -> enablers -> foundational inputs. + +### Step 3: Identify core value generators +- Mark nodes that generate defensible advantage. +- Explain why each is hard to replicate. + +### Step 4: Assess vulnerabilities +- Highlight disruption points and fragility in chain links. + +## Output + +- End-user needs +- Value chain breakdown +- Core value generators +- Potential vulnerabilities + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/value-chain-mapping/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/value-chain-mapping/agents/openai.yaml new file mode 100644 index 0000000..b0e6979 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/value-chain-mapping/agents/openai.yaml @@ -0,0 +1,5 @@ +name: value-chain-mapping +description: Map end-user needs to the full value chain, identify core value generators, and highlight vulnerabilities. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/verification/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/verification/SKILL.md new file mode 100644 index 0000000..bf8305d --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/verification/SKILL.md @@ -0,0 +1,92 @@ +--- +name: verification +description: Verify before claiming completion. No claims without fresh verification evidence. Use before marking work done. +--- + +# Verification Before Completion + +Use when about to claim work is complete, fixed, or passing. + +## The Iron Law + +``` +NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE +``` + +If you haven't run the verification command in this message, you cannot claim it passes. + +## The Gate Function + +Before claiming any status or completion: + +1. **IDENTIFY** - What command proves this claim? +2. **RUN** - Execute the FULL command (fresh, complete) +3. **READ** - Full output, check exit code, count failures +4. **VERIFY** - Does output confirm the claim? + - If NO: State actual status with evidence + - If YES: State claim WITH evidence +5. **ONLY THEN** - Make the claim + +Skip any step = lying, not verifying. + +## What Requires Verification + +| Claim | Requires | Not Sufficient | +|-------|----------|----------------| +| Tests pass | Test command output: 0 failures | Previous run, "should pass" | +| Linter clean | Linter output: 0 errors | Partial check | +| Build succeeds | Build command: exit 0 | Linter passing | +| Bug fixed | Test original symptom: passes | Code changed | +| Phase complete | All objectives verified | Tests passing | +| Task done | Checklist items verified | "I did everything" | + +## Red Flags - STOP + +- Using "should", "probably", "seems to" +- Expressing satisfaction before verification ("Great!", "Done!") +- About to commit/push without verification +- Relying on partial verification +- ANY wording implying success without having run verification + +## Patterns + +**Tests:** +``` +OK: [Run test] [See: 34/34 pass] "All tests pass" +BAD: "Should pass now" +``` + +**Build:** +``` +OK: [Run build] [See: exit 0] "Build passes" +BAD: "Linter passed" (linter != compiler) +``` + +**Task completion:** +``` +OK: Re-read requirements -> checklist -> verify each -> report +BAD: "Tests pass, task complete" +``` + +## Common Rationalizations + +| Excuse | Reality | +|--------|---------| +| "Should work now" | Run the verification | +| "I'm confident" | Confidence != evidence | +| "Just this once" | No exceptions | +| "Partial check is enough" | Partial proves nothing | + +## The Bottom Line + +Run the command. Read the output. Then claim the result. + +No shortcuts. Non-negotiable. + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/verification/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/verification/agents/openai.yaml new file mode 100644 index 0000000..53973d8 --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/verification/agents/openai.yaml @@ -0,0 +1,5 @@ +name: verification +description: Verify before claiming completion. No claims without fresh verification evidence. Use before marking work done. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.agents/skills/writing-plans/SKILL.md b/examples/uj-3-flask-simple/.agents/skills/writing-plans/SKILL.md new file mode 100644 index 0000000..7fca99c --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/writing-plans/SKILL.md @@ -0,0 +1,95 @@ +--- +name: writing-plans +description: Create comprehensive implementation plans with bite-sized tasks. Use when you have requirements before touching code. +--- + +# Writing Plans + +Use when you have requirements for a multi-step task, before touching code. + +## Overview + +Write comprehensive implementation plans assuming the reader has zero context. Document everything: which files to touch, code snippets, testing steps, verification commands. Break into bite-sized tasks. + +## Bite-Sized Task Granularity + +Each step is one action (2-5 minutes): +- "Write the failing test" - step +- "Run it to make sure it fails" - step +- "Implement the minimal code to make the test pass" - step +- "Run the tests and make sure they pass" - step +- "Commit" - step + +## Plan Document Header + +Every plan should start with: + +```markdown +# [Feature Name] Implementation Plan + +**Goal:** [One sentence describing what this builds] + +**Architecture:** [2-3 sentences about approach] + +**Tech Stack:** [Key technologies/libraries] + +--- +``` + +## Task Structure + +```markdown +### Task N: [Component Name] + +**Files:** +- Create: `exact/path/to/file.py` +- Modify: `exact/path/to/existing.py:123-145` +- Test: `tests/exact/path/to/test.py` + +**Step 1: Write the failing test** + +```python +def test_specific_behavior(): + result = function(input) + assert result == expected +``` + +**Step 2: Run test to verify it fails** + +Run: `pytest tests/path/test.py::test_name -v` +Expected: FAIL with "function not defined" + +**Step 3: Write minimal implementation** + +```python +def function(input): + return expected +``` + +**Step 4: Run test to verify it passes** + +Run: `pytest tests/path/test.py::test_name -v` +Expected: PASS + +**Step 5: Commit** + +```bash +git add tests/path/test.py src/path/file.py +git commit -m "feat: add specific feature" +``` +``` + +## Remember + +- Exact file paths always +- Complete code in plan (not "add validation") +- Exact commands with expected output +- DRY, YAGNI, TDD, frequent commits + +## When to Use + +Use this skill when the task directly matches the workflow described above. + +## When Not to Use + +Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response. diff --git a/examples/uj-3-flask-simple/.agents/skills/writing-plans/agents/openai.yaml b/examples/uj-3-flask-simple/.agents/skills/writing-plans/agents/openai.yaml new file mode 100644 index 0000000..030a02b --- /dev/null +++ b/examples/uj-3-flask-simple/.agents/skills/writing-plans/agents/openai.yaml @@ -0,0 +1,5 @@ +name: writing-plans +description: Create comprehensive implementation plans with bite-sized tasks. Use when you have requirements before touching code. +version: 1 +invocation: + trigger: implicit diff --git a/examples/uj-3-flask-simple/.gitignore b/examples/uj-3-flask-simple/.gitignore new file mode 100644 index 0000000..4116dbf --- /dev/null +++ b/examples/uj-3-flask-simple/.gitignore @@ -0,0 +1,48 @@ +# Template .gitignore for Task Management System +# Copy relevant parts to your .gitignore + +# Personal task files +Tasks/*.md +!Tasks/.gitkeep +BACKLOG.md + +# Personal configuration +AGENTS.md # If customized from template +GOALS.md # Personal goals + +# Keep templates and examples +!AGENTS_TEMPLATE.md +!Tasks/example.md + +# Python +__pycache__/ +*.py[cod] +*$py.class +.Python +venv/ +.venv/ +env/ +.env + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store + +# Logs +*.log +logs/ + +# Testing +test_*.py +*.test.py +.pytest_cache/ +.coverage + +# MCP/System +.mcp_cache/ +*.pid +*.lock \ No newline at end of file diff --git a/examples/uj-3-flask-simple/CLAUDE.md b/examples/uj-3-flask-simple/CLAUDE.md new file mode 100644 index 0000000..b8d798f --- /dev/null +++ b/examples/uj-3-flask-simple/CLAUDE.md @@ -0,0 +1,6 @@ +@AGENTS.md + +## Skills + +Canonical skills are available at `.agents/skills/*/SKILL.md` (also accessible via `.claude/skills/`). +To run a skill: read its SKILL.md and follow the instructions within. diff --git a/examples/uj-3-flask-simple/README.md b/examples/uj-3-flask-simple/README.md new file mode 100644 index 0000000..eb780aa --- /dev/null +++ b/examples/uj-3-flask-simple/README.md @@ -0,0 +1,16 @@ +# My Flask App + +A simple REST API built with Flask. + +## Setup + +```bash +pip install -r requirements.txt +python src/app.py +``` + +## Testing + +```bash +pytest tests/ +``` diff --git a/examples/uj-3-flask-simple/Workflows/README.md b/examples/uj-3-flask-simple/Workflows/README.md new file mode 100644 index 0000000..ac04cda --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/README.md @@ -0,0 +1,58 @@ +# Workflows + +Reusable workflows that your AI agent invokes on demand. These are referenced from AGENTS.md and executed when relevant tasks are detected. + +## Daily Workflows + +| Workflow | Time | When to Use | +|----------|------|-------------| +| [Daily Standup](daily-standup.md) | 2 min | Start of day - pick your focus | +| [Backlog Processing](backlog-processing.md) | 5-10 min | End of day or when backlog builds up | +| [Wrap-up Protocol](wrap-up-protocol.md) | 2 min | After completing any work | + +## Weekly Workflows + +| Workflow | Time | When to Use | +|----------|------|-------------| +| [Weekly Review](weekly-review.md) | 15-30 min | Friday PM or Sunday/Monday | + +## Product & Strategy Workflows + +| Workflow | Time | When to Use | +|----------|------|-------------| +| [Research to Feature Pipeline](research-to-feature-pipeline.md) | 20-60 min | Turn interviews into testable product moves | +| [Decision Quality Pipeline](decision-quality-pipeline.md) | 15-45 min | De-risk high-impact decisions | +| [Assumption Validation Pipeline](assumption-validation-pipeline.md) | 15-45 min | Prioritize and test strategic assumptions | +| [Core Strategy Development](core-strategy-development.md) | 30-90 min | Build strategy from context to execution | +| [Opportunity Mapping Pipeline](opportunity-mapping-pipeline.md) | 20-60 min | Select one target opportunity from research | +| [Meeting Prep and Recap](meeting-prep-and-recap.md) | 10-30 min | Prepare for and summarize high-stakes meetings | +| [Stakeholder Politics Copilot](stakeholder-politics-copilot.md) | 20-45 min | Review political risk and comms plans | + +## Quick Reference: Common Prompts + +**Daily** +- "What should I work on today?" +- "What's my most important task right now?" + +**Tasks** +- "Clear my backlog" / "Process my backlog" +- "Mark [task] as done" +- "I'm blocked on [task] because [reason]" + +**Planning** +- "Show my P0 and P1 tasks" +- "Show tasks for goal [goal name]" +- "List blocked tasks" / "What's blocked?" +- "Help me plan next week" +- "Run research to feature pipeline" +- "Run decision quality pipeline" +- "Run stakeholder politics copilot" + +**Review** +- "Weekly review" +- "What did I accomplish this week?" +- "How am I tracking against my goals?" + +**Wrap up** +- "Archive completed tasks" +- "Create an eval for this session" diff --git a/examples/uj-3-flask-simple/Workflows/assumption-validation-pipeline.md b/examples/uj-3-flask-simple/Workflows/assumption-validation-pipeline.md new file mode 100644 index 0000000..84c9ce8 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/assumption-validation-pipeline.md @@ -0,0 +1,26 @@ +# Assumption Validation Pipeline + +Identify what you are betting on and test the riskiest assumptions first. + +## When to Use + +Use before committing major roadmap or strategy bets. + +## Steps + +1. Map assumptions +- Skill: `assumption-mapping` + +2. Prioritize by risk +- Skill: `assumption-prioritization` + +3. Select fast signals +- Skill: `signal-identification` + +4. Design tests +- Skill: `experiment-design` + +## Exit Criteria + +- Top assumptions have explicit risk scores. +- Chosen tests have success/failure thresholds. diff --git a/examples/uj-3-flask-simple/Workflows/backlog-processing.md b/examples/uj-3-flask-simple/Workflows/backlog-processing.md new file mode 100644 index 0000000..43c80e6 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/backlog-processing.md @@ -0,0 +1,91 @@ +# Backlog Processing Workflow + +Turn messy brain dumps into organized, prioritized tasks. + +## When to Use + +- End of day: Process notes captured throughout the day +- Weekly: Clear out accumulated ideas +- After meetings: Turn action items into tasks + +## The Prompt + +``` +Process my backlog +``` + +## Example: Before & After + +### Your BACKLOG.md (messy input) + +```markdown +# Backlog + +- need to follow up with james about the api thing +- Q2 planning thoughts - should we focus on mobile or web first? need to think through this +- bug: users can't upload files larger than 10mb, sarah mentioned this +- write SDK integration patterns doc +- competitor launched new feature, should analyze +- 1:1 with mike tomorrow, prep questions +- expense report overdue +- idea: what if we added AI to the search? +``` + +### The Conversation + +**You:** Process my backlog + +**Claude:** I found 8 items in your backlog. Let me analyze them: + +**Ready to create (5 items):** +| Item | Category | Suggested Priority | +|------|----------|-------------------| +| Follow up with James about API | outreach | P1 | +| Write SDK integration patterns doc | writing | P2 | +| Analyze competitor's new feature | research | P2 | +| Prep questions for Mike 1:1 | admin | P1 (tomorrow) | +| Submit expense report | admin | P1 (overdue) | + +**Needs clarification (2 items):** + +1. "Q2 planning - mobile vs web focus" + - Is this a decision you need to make, or research to inform the decision? + - Should this be a task or added to GOALS.md as a strategic question? + +2. "Bug: file upload > 10mb" + - Is this for you to fix, or should it be tracked in your bug tracker? + - What priority - is it blocking users? + +**Potential duplicate (1 item):** +- "AI search idea" - You have an existing task "Explore AI features for Q2" (68% similar). Should I merge this as a sub-item? + +How would you like me to proceed? + +**You:** The Q2 planning is research I need to do. Bug is P0, users are complaining. Merge the AI idea. + +**Claude:** Got it. Creating 6 tasks: + +✓ Created: Follow up with James about API.md (P1, outreach) +✓ Created: Write SDK integration patterns.md (P2, writing) +✓ Created: Analyze competitor new feature.md (P2, research) +✓ Created: Prep for Mike 1:1.md (P1, admin) +✓ Created: Submit expense report.md (P1, admin) +✓ Created: Research Q2 focus - mobile vs web.md (P2, research) +✓ Created: Fix file upload 10mb limit.md (P0, technical) +✓ Updated: Explore AI features for Q2.md - added search idea + +Backlog cleared. You now have 3 P0/P1 tasks due soon: +1. Fix file upload limit (P0) +2. Expense report (P1, overdue) +3. Mike 1:1 prep (P1, tomorrow) + +Want to start on any of these? + +--- + +## Tips + +- Dump everything into BACKLOG.md throughout the day - don't organize, just capture +- Process at least once per day to keep it manageable +- Be specific when clarifying - Claude will create better tasks +- Review the created tasks briefly to catch any misunderstandings diff --git a/examples/uj-3-flask-simple/Workflows/core-strategy-development.md b/examples/uj-3-flask-simple/Workflows/core-strategy-development.md new file mode 100644 index 0000000..3ca6108 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/core-strategy-development.md @@ -0,0 +1,29 @@ +# Core Strategy Development + +Develop strategy from context to execution with explicit tradeoffs. + +## When to Use + +Use when defining or revising product strategy. + +## Steps + +1. Diagnose strategic crux +- Skill: `crux-diagnosis` + +2. Evaluate competitor posture +- Skill: `competitor-analysis` + +3. Draft structured strategy +- Skill: `structured-product-strategy` + +4. Model limit-based trajectory +- Skill: `limit-based-strategy` + +5. Map value chain and vulnerabilities +- Skill: `value-chain-mapping` + +## Exit Criteria + +- Strategy includes objective, pillars, roadmap direction, and assumptions. +- Value chain vulnerabilities and defensive levers are explicit. diff --git a/examples/uj-3-flask-simple/Workflows/daily-standup.md b/examples/uj-3-flask-simple/Workflows/daily-standup.md new file mode 100644 index 0000000..d35f3da --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/daily-standup.md @@ -0,0 +1,61 @@ +# Daily Standup Workflow + +A quick 2-minute check-in to set your focus for the day. + +## The Prompt + +``` +What should I work on today? +``` + +## Example Conversation + +**You:** What should I work on today? + +**Claude:** Based on your current tasks and goals, here are your top 3 priorities for today: + +**1. [P0] Finalize Q1 roadmap presentation** (estimated: 90 min) +- Due tomorrow for leadership review +- Aligns with your quarterly objective: "Ship Q1 roadmap" + +**2. [P1] Reply to Sarah's partnership email** (estimated: 20 min) +- Been waiting 3 days, relationship maintenance +- Quick win before deep work + +**3. [P1] Write user story for checkout flow** (estimated: 60 min) +- Blocking engineering from starting sprint work +- Supports goal: "Improve activation by 20%" + +You have 2 blocked tasks I noticed: +- "API integration spec" - waiting on engineering estimates +- "User research synthesis" - waiting on interview transcripts + +Want me to help you get started on any of these? + +--- + +## Variations + +### When You're Overwhelmed + +``` +I'm overwhelmed. What's the ONE thing I should focus on? +``` + +### When You Have Limited Time + +``` +I only have 2 hours before meetings. What can I realistically finish? +``` + +### When You Need Context + +``` +Remind me what I was working on yesterday and what's next. +``` + +## Tips + +- Do this first thing, before checking email/Slack +- Keep it under 2 minutes - just pick and start +- If you're stuck deciding, ask Claude to pick for you diff --git a/examples/uj-3-flask-simple/Workflows/decision-quality-pipeline.md b/examples/uj-3-flask-simple/Workflows/decision-quality-pipeline.md new file mode 100644 index 0000000..0f3abd2 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/decision-quality-pipeline.md @@ -0,0 +1,31 @@ +# Decision Quality Pipeline + +Convert ambiguous decisions into auditable, reversible, and role-clear choices. + +## When to Use + +Use when a decision has multiple stakeholders or high impact. + +## Steps + +1. Find root causes and downstream consequences +- Skill: `root-cause-analysis` + +2. Classify reversibility +- Skill: `decision-reversibility` + +3. Structure options cleanly +- Skill: `mece-analysis` +- Skill: `problem-structuring` + +4. Assign decision rights +- Skill: `davci` + +5. Record the decision +- Skill: `decision-journal` + +## Exit Criteria + +- One decider is named. +- Reversibility class is explicit. +- Decision and assumptions are recorded for review. diff --git a/examples/uj-3-flask-simple/Workflows/meeting-prep-and-recap.md b/examples/uj-3-flask-simple/Workflows/meeting-prep-and-recap.md new file mode 100644 index 0000000..1449d13 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/meeting-prep-and-recap.md @@ -0,0 +1,29 @@ +# Meeting Prep And Recap + +Prepare for politically complex meetings and capture outputs consistently. + +## When to Use + +Use before and after high-stakes meetings. + +## Steps + +1. Identify hidden agendas +- Skill: `hidden-agendas` + +2. Build influence options +- Skill: `influence-strategies` + +3. Map meeting-specific dynamics +- Skill: `meeting-power-dynamics` + +4. Prepare difficult conversation script (if needed) +- Skill: `difficult-conversations` + +5. Summarize outcomes +- Skill: `ideas-summary` + +## Exit Criteria + +- Stakeholder dynamics are mapped before meeting. +- Decisions, engagements, and actions are captured after meeting. diff --git a/examples/uj-3-flask-simple/Workflows/opportunity-mapping-pipeline.md b/examples/uj-3-flask-simple/Workflows/opportunity-mapping-pipeline.md new file mode 100644 index 0000000..19254b9 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/opportunity-mapping-pipeline.md @@ -0,0 +1,23 @@ +# Opportunity Mapping Pipeline + +Move from research evidence to a single target opportunity decision. + +## When to Use + +Use during continuous discovery and prioritization. + +## Steps + +1. Intake and normalize inputs +- Skill: `ost-intake` + +2. Build opportunity tree +- Skill: `opportunity-solution-tree` + +3. Select one target opportunity +- Skill: `ost-target-selection` + +## Exit Criteria + +- Selected opportunity is small, distinct, and moment-scoped. +- Recommendation is traceable to interview evidence. diff --git a/examples/uj-3-flask-simple/Workflows/research-to-feature-pipeline.md b/examples/uj-3-flask-simple/Workflows/research-to-feature-pipeline.md new file mode 100644 index 0000000..c6f8eb2 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/research-to-feature-pipeline.md @@ -0,0 +1,34 @@ +# Research To Feature Pipeline + +Transform interview material into testable product moves. + +## When to Use + +Use when you have customer interviews and need a validated path to feature decisions. + +## Steps + +1. Clean transcript +- Skill: `interview-cleanup` +- Output: readable transcript with speaker labels preserved. + +2. Extract JTBD forces +- Skill: `jtbd-extraction` +- Output: pushes, pulls, habits, anxieties grounded in quotes. + +3. Cluster forces across interviews +- Skill: `jtbd-clustering` +- Output: recurring force patterns and unique outliers. + +4. Draft product hypothesis +- Skill: `hypothesis-design` +- Output: one testable hypothesis with measurable outcome. + +5. Design experiment +- Skill: `experiment-design` +- Output: variables, controls, success thresholds, and timeline. + +## Exit Criteria + +- Hypothesis includes action, users, condition, and measurable outcome. +- Experiment includes clear decision rule and confounder controls. diff --git a/examples/uj-3-flask-simple/Workflows/stakeholder-politics-copilot.md b/examples/uj-3-flask-simple/Workflows/stakeholder-politics-copilot.md new file mode 100644 index 0000000..22c8269 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/stakeholder-politics-copilot.md @@ -0,0 +1,29 @@ +# Stakeholder Politics Copilot + +Reduce political risk and improve adoption for feature and strategy proposals. + +## When to Use + +Use before circulating PRDs, updates, or strategy memos. + +## Steps + +1. Build baseline stakeholder map +- Skill: `power-map` + +2. Review stakeholder risks for proposal +- Skill: `stakeholder-risk-review` + +3. Create audience-specific framing +- Skill: `message-framing-comms` + +4. Review executive update quality +- Skill: `executive-update-review` + +5. Generate challenge questions for prep +- Skill: `challenging-stakeholder-questions` + +## Exit Criteria + +- Risks have mitigations and owners. +- Comms plan includes sequence, CTA, and measurable signals. diff --git a/examples/uj-3-flask-simple/Workflows/weekly-review.md b/examples/uj-3-flask-simple/Workflows/weekly-review.md new file mode 100644 index 0000000..9c98150 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/weekly-review.md @@ -0,0 +1,129 @@ +# Weekly Review Workflow + +A 15-30 minute session to reflect on progress and plan ahead. + +## When to Do It + +- Friday afternoon (reflect) +- Sunday evening (prep) +- Monday morning (plan) + +## The Prompts + +### Step 1: Review Completed Work + +``` +What did I accomplish this week? +``` + +**Example response:** + +This week you completed 12 tasks: + +**By Goal Alignment:** +- "Ship Q1 roadmap": 4 tasks (roadmap presentation, 2 specs, stakeholder review) +- "Improve activation": 2 tasks (checkout flow analysis, user interviews) +- "Build SDK expertise": 1 task (integration guide published) +- Maintenance/admin: 5 tasks + +**Highlights:** +- Finished Q1 roadmap presentation (P0) - major milestone +- Published your first SDK integration guide +- Cleared 5 admin tasks that were piling up + +**Time invested:** ~18 hours of focused work logged + +--- + +### Step 2: Check Goal Progress + +``` +How am I tracking against my quarterly goals? +``` + +**Example response:** + +**Q1 Goals Progress (Week 3 of 12):** + +| Goal | Status | Notes | +|------|--------|-------| +| Ship Q1 roadmap | 🟢 On track | Presentation done, specs 60% complete | +| Improve activation by 20% | 🟡 Needs attention | Research done, no implementation started | +| Build thought leadership | 🟢 On track | 1 of 4 planned posts published | + +**Recommendations:** +- Activation goal needs more focus next week +- Consider adding a P1 task to kick off checkout improvements + +--- + +### Step 3: Identify Blockers + +``` +What's blocked or stalled? +``` + +**Example response:** + +**Blocked tasks (3):** +1. "API integration spec" - waiting on engineering estimates (5 days) + → Suggest: Follow up with James Monday AM + +2. "User research synthesis" - waiting on transcripts (3 days) + → Suggest: Check with research team + +3. "Mobile prototype review" - waiting on design (7 days) + → Suggest: Escalate to design lead + +**Stalled tasks (started but no progress this week):** +1. "Competitive analysis doc" - started 2 weeks ago, 20% complete + → Is this still a priority? + +--- + +### Step 4: Plan Next Week + +``` +Help me plan next week. What should my top priorities be? +``` + +**Example response:** + +Based on your goals and current tasks, here's a suggested focus: + +**Must do (P0/P1):** +1. Unblock API integration - follow up Monday +2. Start checkout flow implementation planning +3. Write SDK v2 migration guide (due Friday) + +**Should do (P2):** +4. Finish competitive analysis +5. Prep for Thursday's product review + +**If time allows:** +6. Research AI search feature idea +7. Clean up documentation backlog + +**Time budget:** +- Deep work available: ~15 hours +- Meetings: ~10 hours +- Buffer for urgent items: ~5 hours + +Does this feel right, or should we adjust priorities? + +--- + +## Quick Version (5 minutes) + +If you're short on time: + +``` +Quick weekly review: What did I finish, what's blocked, what's most important next week? +``` + +## Tips + +- Block 30 minutes on your calendar for this +- Do it in a quiet space, not between meetings +- Be honest about what's stalled - it's data, not judgment +- Update GOALS.md if priorities have shifted diff --git a/examples/uj-3-flask-simple/Workflows/wrap-up-protocol.md b/examples/uj-3-flask-simple/Workflows/wrap-up-protocol.md new file mode 100644 index 0000000..2ec6b99 --- /dev/null +++ b/examples/uj-3-flask-simple/Workflows/wrap-up-protocol.md @@ -0,0 +1,76 @@ +# Phase Wrap-Up Protocol + +Apply this when completing phases, features, or fixes. Evidence before claims, always. + +## Before Calling Work Complete + +### 1. Run Verification Commands (Show Output) + +- Run tests: show "X/X pass" (not "tests should pass") +- Run linter: show "0 errors" (not "linter looks clean") +- Run build: show "exit 0" (not "build probably works") +- Test manually: follow actual steps, show results + +### 2. Verify Objectives + +- Read requirements/plan line by line +- Check each objective off with evidence +- If any incomplete, state what remains + +### 3. Update Documentation + +- README status section - what works now +- Any testing docs if new features added +- Spec/plan if implementation differed + +### 4. Proactive Completion Signal + +Say explicitly: "Let's wrap up [Phase/Feature X]" + +### 5. Walk Through Testing + +Concrete steps: "Click X, you should see Y" +Not vague: "test the feature" + +### 6. Wait for Confirmation + +Never proceed to next phase without user sign-off. + +### 7. Memory Sweep + +Ask: "What did I learn this session that future sessions need to know?" + +Check: +- [ ] Any gotchas discovered? -> Add to AGENTS.md +- [ ] Any patterns that worked well? -> Add to AGENTS.md +- [ ] Any divergence from spec? -> Update spec with decision + rationale +- [ ] Any new capabilities? -> Update README +- [ ] Any new testing needed? -> Document + +Don't let hard-won knowledge die with this session. + +### 8. Commit Readiness + +- Suggest clear commit message +- Verify all changed files included +- Check no temporary/debug code remains + +## Red Flags - Never Say + +- "Should work now" +- "Tests passed" (without showing output) +- "Phase complete, moving to Phase X" (without confirmation) + +## Scale to Work Size + +- **Big phases**: Full checklist +- **Small tasks**: Abbreviated but still intentional +- **Always**: Verify it works and signal completion clearly + +## Why This Matters + +- Prevents building on broken foundations +- Maintains documentation accuracy +- Creates natural stopping points +- Ensures we can return to working state +- Makes each phase independently valuable diff --git a/examples/uj-3-flask-simple/requirements.txt b/examples/uj-3-flask-simple/requirements.txt new file mode 100644 index 0000000..b6a7500 --- /dev/null +++ b/examples/uj-3-flask-simple/requirements.txt @@ -0,0 +1,2 @@ +flask>=3.0.0 +pytest>=7.0.0 diff --git a/examples/uj-3-flask-simple/skills b/examples/uj-3-flask-simple/skills new file mode 120000 index 0000000..5018230 --- /dev/null +++ b/examples/uj-3-flask-simple/skills @@ -0,0 +1 @@ +.agents/skills \ No newline at end of file diff --git a/examples/uj-3-flask-simple/src/app.py b/examples/uj-3-flask-simple/src/app.py new file mode 100644 index 0000000..646f184 --- /dev/null +++ b/examples/uj-3-flask-simple/src/app.py @@ -0,0 +1,18 @@ +"""Simple Flask application.""" +from flask import Flask, jsonify + +app = Flask(__name__) + + +@app.route("/health") +def health(): + return jsonify({"status": "ok"}) + + +@app.route("/api/items") +def list_items(): + return jsonify({"items": []}) + + +if __name__ == "__main__": + app.run(debug=True) diff --git a/examples/uj-4-rust-antigravity/AGENTS.md b/examples/uj-4-rust-antigravity/AGENTS.md new file mode 100644 index 0000000..3771bf6 --- /dev/null +++ b/examples/uj-4-rust-antigravity/AGENTS.md @@ -0,0 +1,9 @@ +# Project Agents + +## API Developer +Focus on HTTP routing, request handling, and API design patterns. +Use axum idioms and follow REST conventions. + +## Core Logic +Focus on business rules, domain models, and data transformations. +Keep this crate free of framework dependencies. diff --git a/examples/uj-4-rust-antigravity/Cargo.toml b/examples/uj-4-rust-antigravity/Cargo.toml new file mode 100644 index 0000000..d8bc30a --- /dev/null +++ b/examples/uj-4-rust-antigravity/Cargo.toml @@ -0,0 +1,7 @@ +[workspace] +members = ["api", "core", "shared"] +resolver = "2" + +[workspace.package] +version = "0.1.0" +edition = "2021" diff --git a/examples/uj-4-rust-antigravity/api/Cargo.toml b/examples/uj-4-rust-antigravity/api/Cargo.toml new file mode 100644 index 0000000..51b1036 --- /dev/null +++ b/examples/uj-4-rust-antigravity/api/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "api" +version.workspace = true +edition.workspace = true + +[dependencies] +core = { path = "../core" } +shared = { path = "../shared" } +axum = "0.7" +tokio = { version = "1", features = ["full"] } diff --git a/examples/uj-4-rust-antigravity/core/Cargo.toml b/examples/uj-4-rust-antigravity/core/Cargo.toml new file mode 100644 index 0000000..1f5972b --- /dev/null +++ b/examples/uj-4-rust-antigravity/core/Cargo.toml @@ -0,0 +1,7 @@ +[package] +name = "core" +version.workspace = true +edition.workspace = true + +[dependencies] +shared = { path = "../shared" } diff --git a/examples/uj-4-rust-antigravity/shared/Cargo.toml b/examples/uj-4-rust-antigravity/shared/Cargo.toml new file mode 100644 index 0000000..eec109c --- /dev/null +++ b/examples/uj-4-rust-antigravity/shared/Cargo.toml @@ -0,0 +1,7 @@ +[package] +name = "shared" +version.workspace = true +edition.workspace = true + +[dependencies] +serde = { version = "1", features = ["derive"] } diff --git a/pytest.ini b/pytest.ini new file mode 100644 index 0000000..956f3a5 --- /dev/null +++ b/pytest.ini @@ -0,0 +1,3 @@ +[pytest] +testpaths = tests +addopts = --junitxml=tests/results/python/report.xml --tb=short diff --git a/setup.sh b/setup.sh index 02ce16f..bf89fa9 100755 --- a/setup.sh +++ b/setup.sh @@ -1,15 +1,20 @@ -#!/usr/bin/env bash +#!/bin/sh # Personal OS Setup Script # Creates directories, copies templates, and guides you through goals creation +# Supports AI-assisted setup via --ai flag set -e -# Colors for output +# Resolve script's own directory before any cd +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" + +# Colors for output (portable via tput or ANSI) GREEN='\033[0;32m' BLUE='\033[0;34m' YELLOW='\033[1;33m' -NC='\033[0m' # No Color +RED='\033[0;31m' +NC='\033[0m' print_header() { echo "" @@ -20,17 +25,403 @@ print_header() { } print_success() { - echo -e "${GREEN}✓${NC} $1" + printf "${GREEN}✓${NC} %s\n" "$1" } print_info() { - echo -e "${BLUE}ℹ${NC} $1" + printf "${BLUE}ℹ${NC} %s\n" "$1" } print_warning() { - echo -e "${YELLOW}!${NC} $1" + printf "${YELLOW}!${NC} %s\n" "$1" +} + +print_error() { + printf "${RED}✗${NC} %s\n" "$1" +} + +show_help() { + cat << 'USAGE' +Usage: setup.sh [OPTIONS] + +Personal OS setup — classic interactive or AI-assisted. + +Options: + --ai Enable AI-assisted setup (skips classic questionnaire) + --runtime LIST Comma-separated runtimes to target (claude,cursor,cline,antigravity) + Default: all detected runtimes + --dry-run Preview what AI would generate without writing files + --track Keep generated files tracked in git (default: gitignored) + --target PATH Run setup against a different directory (default: current directory) + --auto Skip interactive approval (requires --runtime) + --remove Uninstall agentic-os generated files using manifest + --help Show this help message + +Examples: + ./setup.sh Classic interactive setup + ./setup.sh --ai AI-assisted setup for all runtimes + ./setup.sh --ai --runtime claude AI-assisted setup for Claude Code only + ./setup.sh --ai --dry-run Preview AI proposals without writing + ./setup.sh --ai --target ./my-project Run against a different directory + ./setup.sh --ai --auto --runtime claude Unattended setup (no approval prompt) + ./setup.sh --remove Clean uninstall of generated files +USAGE +} + +# --- Flag Parsing --- + +MODE="classic" +RUNTIMES="" +DRY_RUN=false +TRACK=false +AUTO=false +TARGET_DIR="" +VALID_RUNTIMES="claude cursor cline antigravity" + +while [ $# -gt 0 ]; do + case "$1" in + --help) + show_help + exit 0 + ;; + --ai) + MODE="ai" + shift + ;; + --runtime) + if [ -z "$2" ] || [ "$(echo "$2" | cut -c1)" = "-" ]; then + print_error "Error: --runtime requires a comma-separated list" + echo "Valid runtimes: claude, cursor, cline, antigravity" + exit 1 + fi + RUNTIMES="$2" + shift 2 + ;; + --dry-run) + DRY_RUN=true + shift + ;; + --track) + TRACK=true + shift + ;; + --target) + if [ -z "$2" ] || [ "$(echo "$2" | cut -c1)" = "-" ]; then + print_error "Error: --target requires a directory path" + exit 1 + fi + TARGET_DIR="$2" + shift 2 + ;; + --auto) + AUTO=true + shift + ;; + --remove) + MODE="remove" + shift + ;; + *) + print_error "Unknown option: $1" + echo "Run 'setup.sh --help' for usage information." + exit 1 + ;; + esac +done + +# --- Validate --runtime values --- + +validate_runtimes() { + OLD_IFS="$IFS" + IFS=',' + set -- $RUNTIMES + IFS="$OLD_IFS" + for rt in "$@"; do + valid=false + for vrt in $VALID_RUNTIMES; do + if [ "$rt" = "$vrt" ]; then + valid=true + break + fi + done + if [ "$valid" = "false" ]; then + print_error "Invalid runtime: $rt" + echo "Valid runtimes: claude, cursor, cline, antigravity" + exit 1 + fi + done +} + +if [ -n "$RUNTIMES" ]; then + validate_runtimes +fi + +# --- Validate --auto requires --runtime --- + +if [ "$AUTO" = "true" ] && [ -z "$RUNTIMES" ]; then + print_error "Error: --auto requires explicit --runtime (cannot auto-detect in unattended mode)" + echo "Example: setup.sh --ai --auto --runtime claude,cursor" + exit 1 +fi + +# --- Resolve target directory --- + +if [ -n "$TARGET_DIR" ]; then + if [ ! -d "$TARGET_DIR" ]; then + print_error "Error: target directory does not exist: $TARGET_DIR" + exit 1 + fi + cd "$TARGET_DIR" + print_info "Target directory: $TARGET_DIR" +fi + +# --- Remove Mode --- + +handle_remove() { + MANIFEST=".agents/.agentic-os-manifest.json" + + if ! command -v jq >/dev/null 2>&1; then + print_error "Error: jq is required for --remove. Install:" + echo " macOS: brew install jq" + echo " Linux: apt install jq (or yum install jq)" + exit 2 + fi + + if [ ! -f "$MANIFEST" ]; then + print_info "No agentic-os installation found (no manifest at $MANIFEST)" + exit 0 + fi + + print_header "Removing Agentic-OS Generated Files" + + file_count=$(jq -r '.files | length' "$MANIFEST") + i=0 + while [ "$i" -lt "$file_count" ]; do + filepath=$(jq -r ".files[$i].path" "$MANIFEST") + if [ -f "$filepath" ]; then + rm "$filepath" + print_success "Deleted: $filepath" + else + print_warning "Already missing: $filepath" + fi + i=$((i + 1)) + done + + # Remove gitignore managed block + if [ -f ".gitignore" ]; then + if grep -q "# === AGENTIC-OS GENERATED" ".gitignore"; then + # Remove the managed block (between start and end markers inclusive) + sed_tmp=".gitignore.tmp.$$" + awk '/^# === AGENTIC-OS GENERATED/{skip=1; next} /^# === END AGENTIC-OS GENERATED/{skip=0; next} !skip' ".gitignore" > "$sed_tmp" + mv "$sed_tmp" ".gitignore" + print_success "Removed gitignore managed block" + fi + fi + + # Remove context bridge file + if [ -f ".agents/.agentic-os-setup-context.json" ]; then + rm ".agents/.agentic-os-setup-context.json" + print_success "Deleted: .agents/.agentic-os-setup-context.json" + fi + + # Remove manifest itself + rm "$MANIFEST" + print_success "Deleted: $MANIFEST" + + echo "" + print_success "Agentic-OS uninstall complete. Your original files are untouched." + exit 0 } +if [ "$MODE" = "remove" ]; then + handle_remove +fi + +# --- AI-Assisted Mode --- + +handle_ai() { + SKILL_DIR=".agents/skills/agentic-os-setup" + SKILL_FILE_ABS="$SCRIPT_DIR/$SKILL_DIR/SKILL.md" + CONTEXT_FILE=".agents/.agentic-os-setup-context.json" + + # Verify skill exists (ships in-tree with agentic-os, not in target dir) + if [ ! -f "$SKILL_FILE_ABS" ]; then + print_error "AI-installer skill not found at $SKILL_FILE_ABS" + echo "This file should ship with agentic-os. Please check your installation." + exit 1 + fi + + # Check jq availability (non-blocking for --ai, just warn) + if ! command -v jq >/dev/null 2>&1; then + print_warning "jq not found. Install jq for --remove support later:" + echo " macOS: brew install jq" + echo " Linux: apt install jq (or yum install jq)" + fi + + # --- Workspace Bootstrapping (copy infrastructure, never overwrite) --- + print_header "Bootstrapping Workspace" + + # Directories + for dir in "Tasks" "Knowledge"; do + if [ -d "$dir" ]; then + print_info "Directory exists: $dir/" + else + mkdir -p "$dir" + print_success "Created: $dir/" + fi + done + + # BACKLOG.md + if [ ! -f "BACKLOG.md" ]; then + cat > "BACKLOG.md" << 'BACKLOGEOF' +# Backlog + +Drop raw notes or todos here. Say `process my backlog` when you're ready for triage. +BACKLOGEOF + print_success "Created: BACKLOG.md" + else + print_info "Exists: BACKLOG.md" + fi + + # Workflows + if [ ! -d "Workflows" ] && [ -d "$SCRIPT_DIR/Workflows" ]; then + cp -r "$SCRIPT_DIR/Workflows" "Workflows" + print_success "Copied: Workflows/" + else + print_info "Exists: Workflows/" + fi + + # .agents/skills (all canonical skill packs) + if [ ! -d ".agents/skills" ]; then + mkdir -p ".agents" + cp -r "$SCRIPT_DIR/.agents/skills" ".agents/skills" + print_success "Copied: .agents/skills/ (all canonical skill packs)" + else + # Skills dir exists — ensure the setup skill is present + if [ ! -d ".agents/skills/agentic-os-setup" ]; then + cp -r "$SCRIPT_DIR/.agents/skills/agentic-os-setup" ".agents/skills/agentic-os-setup" + print_success "Copied: .agents/skills/agentic-os-setup/" + else + print_info "Exists: .agents/skills/agentic-os-setup/" + fi + fi + + # Bridge: .claude/skills + if [ ! -d ".claude" ]; then + mkdir -p ".claude" + fi + if [ ! -e ".claude/skills" ]; then + # No skills path at all — create symlink + ln -sfn "../.agents/skills" ".claude/skills" + print_success "Created symlink: .claude/skills -> ../.agents/skills" + elif [ -L ".claude/skills" ]; then + print_info "Exists: .claude/skills symlink" + elif [ -d ".claude/skills" ]; then + # .claude/skills is a real directory (not symlink) — ensure agentic-os-setup is there too + if [ ! -d ".claude/skills/agentic-os-setup" ]; then + cp -r "$SCRIPT_DIR/.agents/skills/agentic-os-setup" ".claude/skills/agentic-os-setup" + print_success "Copied: .claude/skills/agentic-os-setup/ (bridge directory)" + else + print_info "Exists: .claude/skills/agentic-os-setup/" + fi + fi + if [ ! -L "skills" ] && [ ! -e "skills" ]; then + ln -s ".agents/skills" "skills" + print_success "Created symlink: skills -> .agents/skills" + else + print_info "Exists: skills symlink" + fi + + # .gitignore from template (never overwrite) + if [ ! -f ".gitignore" ] && [ -f "$SCRIPT_DIR/System/templates/gitignore" ]; then + cp "$SCRIPT_DIR/System/templates/gitignore" ".gitignore" + print_success "Copied: .gitignore (from template)" + else + print_info "Exists: .gitignore (preserving your version)" + fi + + # Ensure CLAUDE.md has skills reference (append if missing, never overwrite existing content) + if [ -f "CLAUDE.md" ]; then + if ! grep -q ".agents/skills" "CLAUDE.md"; then + printf '\n## Skills\n\nCanonical skills are available at `.agents/skills/*/SKILL.md` (also accessible via `.claude/skills/`).\nTo run a skill: read its SKILL.md and follow the instructions within.\n' >> "CLAUDE.md" + print_success "Appended skills reference to CLAUDE.md" + else + print_info "CLAUDE.md already references skills" + fi + else + cat > "CLAUDE.md" << 'CLAUDEEOF' +@AGENTS.md + +## Skills + +Canonical skills are available at `.agents/skills/*/SKILL.md` (also accessible via `.claude/skills/`). +To run a skill: read its SKILL.md and follow the instructions within. +CLAUDEEOF + print_success "Created: CLAUDE.md (with AGENTS.md reference + skills)" + fi + + # --- End Bootstrap --- + + # Build runtime list for context bridge + if [ -z "$RUNTIMES" ]; then + runtime_json='["claude","cursor","cline","antigravity"]' + else + runtime_json="[" + first=true + OLD_IFS="$IFS" + IFS=',' + for rt in $RUNTIMES; do + if [ "$first" = "true" ]; then + runtime_json="${runtime_json}\"${rt}\"" + first=false + else + runtime_json="${runtime_json},\"${rt}\"" + fi + done + IFS="$OLD_IFS" + runtime_json="${runtime_json}]" + fi + + # Write context bridge file (skill is now local after bootstrap) + mkdir -p "$(dirname "$CONTEXT_FILE")" + cat > "$CONTEXT_FILE" << EOF +{ + "runtimes": ${runtime_json}, + "dry_run": ${DRY_RUN}, + "track": ${TRACK}, + "auto": ${AUTO} +} +EOF + + print_header "AI-Assisted Setup Ready" + + print_success "Workspace bootstrapped" + print_success "Skill installed: .agents/skills/agentic-os-setup/SKILL.md" + print_success "Context written: $CONTEXT_FILE" + echo "" + print_info "Runtimes: $(echo "$runtime_json" | tr -d '[]"')" + [ "$DRY_RUN" = "true" ] && print_info "Mode: dry-run (no files will be written)" + [ "$AUTO" = "true" ] && print_info "Mode: auto-approval (will write without interactive confirmation)" + [ "$TRACK" = "true" ] && print_info "Track: generated files will be committed (not gitignored)" + echo "" + echo "Now invoke the AI-installer skill in your AI tool:" + echo "" + echo " Claude Code: /agentic-os-setup (or say \"Run the agentic-os-setup skill\")" + echo " Cursor: \"Run the agentic-os-setup skill\"" + echo " Cline: \"Run the agentic-os-setup skill\"" + echo " Antigravity: \"Run the agentic-os-setup skill\"" + echo "" + print_info "Target repo: $(pwd)" + print_info "The AI will scan your repo, infer GOALS.md, and generate runtime-specific configuration." + exit 0 +} + +if [ "$MODE" = "ai" ]; then + handle_ai +fi + +# --- Classic Mode (unchanged behavior below this line) --- + ensure_symlink() { local target="$1" local link_path="$2" @@ -55,14 +446,12 @@ ask_question() { local example="$2" local response="" - # Print prompt to terminal (stderr so it's not captured) echo "" >&2 echo "$prompt" >&2 if [ -n "$example" ]; then - echo -e "${BLUE}$example${NC}" >&2 + printf "${BLUE}%s${NC}\n" "$example" >&2 fi read -r response - # Return answer to stdout (gets captured) echo "$response" } @@ -89,7 +478,7 @@ echo " 3. Configure your AI assistant" echo "" echo "Takes about 2 minutes. Be honest and specific." echo "" -read -p "Press Enter to begin..." +read -r -p "Press Enter to begin..." # Create directories print_header "Creating Workspace" @@ -152,7 +541,7 @@ echo "" echo "Be honest and specific - this is for you, not anyone else." echo "You can always edit GOALS.md later to refine your thinking." echo "" -read -p "Ready to dive in? Press Enter to start..." +read -r -p "Ready to dive in? Press Enter to start..." # Collect answers (keeping it short - 5 essential questions) @@ -310,5 +699,7 @@ echo "3. Confirm bridge symlinks: .claude/skills and skills" echo "4. Start adding tasks or notes to BACKLOG.md" echo "5. Tell your AI: 'Read AGENTS.md and help me process my backlog'" echo "" +echo "Want AI-powered setup? Run: setup.sh --ai" +echo "" print_success "Happy organizing!" echo "" diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..ce587d8 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,40 @@ +"""Pytest configuration — writes plain text report to tests/results/python/report.txt.""" + +from pathlib import Path + + +def pytest_sessionfinish(session, exitstatus): + results_dir = Path(__file__).parent / "results" / "python" + results_dir.mkdir(parents=True, exist_ok=True) + + passed = session.testscollected - session.testsfailed + lines = [ + f"Pytest Results — {session.startdir}", + f"{'PASS' if exitstatus == 0 else 'FAIL'}: {passed}/{session.testscollected} passed", + "", + ] + + for item in session.items: + rep = item.stash.get(_report_key, None) + if rep: + status = "PASS" if rep.passed else "FAIL" + lines.append(f" {status}: {item.nodeid}") + + report_path = results_dir / "report.txt" + report_path.write_text("\n".join(lines) + "\n") + + +_report_key = None + + +def pytest_configure(config): + global _report_key + from _pytest.stash import StashKey + _report_key = StashKey() + + +def pytest_runtest_makereport(item, call): + if call.when == "call" and _report_key is not None: + from _pytest.runner import TestReport + rep = TestReport.from_item_and_call(item, call) + item.stash[_report_key] = rep diff --git a/tests/test_content.py b/tests/test_content.py new file mode 100644 index 0000000..cc02a2a --- /dev/null +++ b/tests/test_content.py @@ -0,0 +1,335 @@ +""" +Content validation tests for agentic-os AI-installer generated output. + +Validates structural correctness of: +- Manifest JSON schema +- .mdc YAML frontmatter +- Glob specificity rules +- Managed block marker syntax +- Gitignore block structure +- Cursor file numbering + +Run: pytest tests/test_content.py +""" + +import json +import os +import re +from pathlib import Path + +import pytest +import yaml + +REPO_ROOT = Path(__file__).parent.parent +FIXTURES_DIR = REPO_ROOT / "examples" +SKILL_DIR = REPO_ROOT / ".agents" / "skills" / "agentic-os-setup" + + +# ============================================================ +# Scenario 1: Manifest schema validation +# ============================================================ + + +class TestManifestSchema: + """Validates manifest JSON structure meets the defined schema.""" + + SAMPLE_MANIFEST = { + "version": "1.0.0", + "created_at": "2026-06-20T15:30:00Z", + "complexity_tier": "simple", + "runtimes_targeted": ["claude"], + "files": [ + { + "path": "CLAUDE.md", + "created_at": "2026-06-20T15:30:00Z", + "content_hash": "sha256:abc123def456", + } + ], + "denied_relationships": [], + "detected_frameworks": [], + } + + def test_required_top_level_fields(self): + required = [ + "version", + "created_at", + "complexity_tier", + "runtimes_targeted", + "files", + "denied_relationships", + "detected_frameworks", + ] + for field in required: + assert field in self.SAMPLE_MANIFEST + + def test_version_is_semver(self): + version = self.SAMPLE_MANIFEST["version"] + assert re.match(r"^\d+\.\d+\.\d+$", version) + + def test_complexity_tier_valid_values(self): + valid_tiers = {"zero", "simple", "multi", "complex"} + assert self.SAMPLE_MANIFEST["complexity_tier"] in valid_tiers + + def test_runtimes_are_valid(self): + valid_runtimes = {"claude", "cursor", "cline", "antigravity"} + for rt in self.SAMPLE_MANIFEST["runtimes_targeted"]: + assert rt in valid_runtimes + + def test_files_have_required_fields(self): + for f in self.SAMPLE_MANIFEST["files"]: + assert "path" in f + assert "created_at" in f + assert "content_hash" in f + + def test_content_hash_format(self): + for f in self.SAMPLE_MANIFEST["files"]: + assert f["content_hash"].startswith("sha256:") + hash_part = f["content_hash"].split(":")[1] + assert len(hash_part) > 0 + assert re.match(r"^[a-f0-9]+$", hash_part) + + +# ============================================================ +# Scenario 2: .mdc YAML frontmatter validation +# ============================================================ + + +class TestMdcFrontmatter: + """Validates .mdc files have proper YAML frontmatter.""" + + @pytest.fixture + def mdc_files(self): + """Collect all .mdc files from fixtures.""" + files = [] + for fixture in FIXTURES_DIR.iterdir(): + if fixture.is_dir(): + cursor_dir = fixture / ".cursor" / "rules" + if cursor_dir.exists(): + files.extend(cursor_dir.glob("*.mdc")) + return files + + def test_mdc_files_exist(self, mdc_files): + assert len(mdc_files) > 0, "No .mdc files found in fixtures" + + def test_all_mdc_have_frontmatter(self, mdc_files): + for mdc_file in mdc_files: + content = mdc_file.read_text() + assert content.startswith("---"), ( + f"{mdc_file.name} missing YAML frontmatter start" + ) + parts = content.split("---", 2) + assert len(parts) >= 3, ( + f"{mdc_file.name} missing YAML frontmatter end delimiter" + ) + + def test_frontmatter_has_description(self, mdc_files): + for mdc_file in mdc_files: + content = mdc_file.read_text() + parts = content.split("---", 2) + fm = yaml.safe_load(parts[1]) + assert "description" in fm, ( + f"{mdc_file.name} frontmatter missing 'description'" + ) + assert len(fm["description"]) > 0 + + def test_frontmatter_has_globs(self, mdc_files): + for mdc_file in mdc_files: + content = mdc_file.read_text() + parts = content.split("---", 2) + fm = yaml.safe_load(parts[1]) + assert "globs" in fm, f"{mdc_file.name} frontmatter missing 'globs'" + + +# ============================================================ +# Scenario 3: Glob specificity (no bare *) +# ============================================================ + + +class TestGlobSpecificity: + """Ensures no .mdc file uses bare '*' as its glob.""" + + @pytest.fixture + def mdc_globs(self): + """Extract globs from all fixture .mdc files.""" + globs = [] + for fixture in FIXTURES_DIR.iterdir(): + if fixture.is_dir(): + cursor_dir = fixture / ".cursor" / "rules" + if cursor_dir.exists(): + for mdc_file in cursor_dir.glob("*.mdc"): + content = mdc_file.read_text() + parts = content.split("---", 2) + if len(parts) >= 3: + fm = yaml.safe_load(parts[1]) + if "globs" in fm: + globs.append( + (mdc_file.name, fm["globs"]) + ) + return globs + + def test_no_bare_star_glob(self, mdc_globs): + for filename, glob_value in mdc_globs: + glob_str = str(glob_value) + individual_globs = [g.strip() for g in glob_str.split(",")] + for g in individual_globs: + assert g != "*", ( + f"{filename} uses bare '*' glob (too broad)" + ) + assert g != "**/*", ( + f"{filename} uses '**/*' glob (matches everything)" + ) + + +# ============================================================ +# Scenario 4: Managed block marker syntax +# ============================================================ + + +class TestManagedBlockMarkers: + """Validates managed block marker format in adapter docs.""" + + MARKER_START_PATTERN = re.compile( + r"" + ) + MARKER_END = "" + + def test_antigravity_adapter_documents_marker_format(self): + adapter = SKILL_DIR / "adapters" / "antigravity.md" + content = adapter.read_text() + assert "" in content + + def test_skill_md_documents_marker_format(self): + skill = SKILL_DIR / "SKILL.md" + content = skill.read_text() + assert "" in content + + def test_marker_format_in_examples(self): + example = SKILL_DIR / "examples" / "complex-output.md" + content = example.read_text() + assert self.MARKER_START_PATTERN.search(content), ( + "complex-output.md missing valid managed block start marker" + ) + assert self.MARKER_END in content + + +# ============================================================ +# Scenario 5: Gitignore block structure +# ============================================================ + + +class TestGitignoreBlock: + """Validates the gitignore managed block format in SKILL.md.""" + + def test_skill_defines_gitignore_block_format(self): + skill = SKILL_DIR / "SKILL.md" + content = skill.read_text() + assert "# === AGENTIC-OS GENERATED" in content + assert "# === END AGENTIC-OS GENERATED ===" in content + + def test_block_has_start_and_end_delimiters(self): + skill = SKILL_DIR / "SKILL.md" + content = skill.read_text() + start_count = content.count("# === AGENTIC-OS GENERATED") + end_count = content.count("# === END AGENTIC-OS GENERATED ===") + assert start_count > 0 + assert end_count > 0 + assert start_count == end_count, ( + "Mismatched gitignore block delimiters" + ) + + +# ============================================================ +# Scenario 6: Cursor file numbering respect +# ============================================================ + + +class TestCursorNumbering: + """Validates numbering detection logic in fixtures.""" + + def test_uj1_has_non_contiguous_numbering(self): + """UJ-1 fixture has 002, 003, 005 — next should be 006 or higher.""" + cursor_dir = FIXTURES_DIR / "uj-1-node-monorepo" / ".cursor" / "rules" + numbers = [] + for f in cursor_dir.glob("*.mdc"): + match = re.match(r"^(\d+)", f.name) + if match: + numbers.append(int(match.group(1))) + numbers.sort() + assert numbers == [2, 3, 5], ( + f"UJ-1 fixture numbers unexpected: {numbers}" + ) + next_available = max(numbers) + 1 + assert next_available == 6 + + def test_uj2_uses_800_band(self): + """UJ-2 fixture has 800-809 — next should be 810.""" + cursor_dir = ( + FIXTURES_DIR / "uj-2-architect-monorepo" / ".cursor" / "rules" + ) + numbers = [] + for f in cursor_dir.glob("*.mdc"): + match = re.match(r"^(\d+)", f.name) + if match: + numbers.append(int(match.group(1))) + numbers.sort() + assert min(numbers) == 800 + assert max(numbers) == 809 + assert len(numbers) == 10 + next_available = max(numbers) + 1 + assert next_available == 810 + + +# ============================================================ +# Scenario 7: Skill file structure completeness +# ============================================================ + + +class TestSkillStructure: + """Validates the skill directory has all required files.""" + + def test_skill_md_exists(self): + assert (SKILL_DIR / "SKILL.md").exists() + + def test_catalog_exists(self): + assert (SKILL_DIR / "catalog.md").exists() + + def test_all_templates_exist(self): + expected = [ + "persona-routing.md", + "scope-isolation.md", + "cross-reference.md", + "naming-enforcement.md", + "quality-gates.md", + ] + for name in expected: + assert (SKILL_DIR / "templates" / name).exists(), ( + f"Missing template: {name}" + ) + + def test_all_adapters_exist(self): + expected = ["claude.md", "cursor.md", "cline.md", "antigravity.md"] + for name in expected: + assert (SKILL_DIR / "adapters" / name).exists(), ( + f"Missing adapter: {name}" + ) + + def test_all_examples_exist(self): + expected = ["simple-output.md", "complex-output.md"] + for name in expected: + assert (SKILL_DIR / "examples" / name).exists(), ( + f"Missing example: {name}" + ) + + def test_all_fixtures_exist(self): + expected = [ + "uj-1-node-monorepo", + "uj-2-architect-monorepo", + "uj-3-flask-simple", + "uj-4-rust-antigravity", + ] + for name in expected: + assert (FIXTURES_DIR / name).is_dir(), ( + f"Missing fixture: {name}" + ) diff --git a/tests/test_setup.sh b/tests/test_setup.sh new file mode 100755 index 0000000..52e0dcb --- /dev/null +++ b/tests/test_setup.sh @@ -0,0 +1,246 @@ +#!/bin/sh +# Shell test runner for setup.sh flag parsing and mode routing. +# Runs against the test fixtures in examples/. +# Results written to tests/results/shell/ + +set -e + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +SETUP="$REPO_ROOT/setup.sh" +RESULTS="$SCRIPT_DIR/results/shell" + +# Counters +PASS=0 +FAIL=0 +TOTAL=0 + +mkdir -p "$RESULTS" + +# --- Test Helpers --- + +assert_exit() { + test_name="$1" + expected_exit="$2" + shift 2 + TOTAL=$((TOTAL + 1)) + + actual_output=$("$@" 2>&1) || true + # Re-run to capture exit code + set +e + "$@" > /dev/null 2>&1 + actual_exit=$? + set -e + + if [ "$actual_exit" -eq "$expected_exit" ]; then + PASS=$((PASS + 1)) + printf " PASS: %s\n" "$test_name" + else + FAIL=$((FAIL + 1)) + printf " FAIL: %s (expected exit %d, got %d)\n" "$test_name" "$expected_exit" "$actual_exit" + printf " Output: %s\n" "$actual_output" >> "$RESULTS/failures.log" + fi +} + +assert_output_contains() { + test_name="$1" + pattern="$2" + shift 2 + TOTAL=$((TOTAL + 1)) + + actual_output=$("$@" 2>&1) || true + + if echo "$actual_output" | grep -qF -- "$pattern"; then + PASS=$((PASS + 1)) + printf " PASS: %s\n" "$test_name" + else + FAIL=$((FAIL + 1)) + printf " FAIL: %s (output missing: %s)\n" "$test_name" "$pattern" + printf " Full output: %s\n" "$actual_output" >> "$RESULTS/failures.log" + fi +} + +assert_file_exists() { + test_name="$1" + filepath="$2" + TOTAL=$((TOTAL + 1)) + + if [ -f "$filepath" ]; then + PASS=$((PASS + 1)) + printf " PASS: %s\n" "$test_name" + else + FAIL=$((FAIL + 1)) + printf " FAIL: %s (file not found: %s)\n" "$test_name" "$filepath" + fi +} + +assert_file_not_exists() { + test_name="$1" + filepath="$2" + TOTAL=$((TOTAL + 1)) + + if [ ! -f "$filepath" ]; then + PASS=$((PASS + 1)) + printf " PASS: %s\n" "$test_name" + else + FAIL=$((FAIL + 1)) + printf " FAIL: %s (file should not exist: %s)\n" "$test_name" "$filepath" + fi +} + +# --- Clean state --- + +rm -f "$RESULTS/failures.log" +printf "Shell Test Runner — %s\n\n" "$(date)" + +# ============================================================ +# Test Suite 1: --help +# ============================================================ + +printf "Suite 1: --help\n" + +assert_exit "help exits 0" 0 sh "$SETUP" --help +assert_output_contains "help shows --ai" "--ai" sh "$SETUP" --help +assert_output_contains "help shows --runtime" "--runtime" sh "$SETUP" --help +assert_output_contains "help shows --target" "--target" sh "$SETUP" --help +assert_output_contains "help shows --auto" "--auto" sh "$SETUP" --help +assert_output_contains "help shows --remove" "--remove" sh "$SETUP" --help + +echo "" + +# ============================================================ +# Test Suite 2: --ai routing +# ============================================================ + +printf "Suite 2: --ai routing\n" + +assert_exit "ai mode succeeds with skill present" 0 sh "$SETUP" --ai --runtime claude +assert_output_contains "ai prints skill installed" "Skill installed" sh "$SETUP" --ai --runtime claude +assert_output_contains "ai prints context written" "Context written" sh "$SETUP" --ai --runtime claude + +# Clean up context file +rm -f "$REPO_ROOT/.agents/.agentic-os-setup-context.json" + +echo "" + +# ============================================================ +# Test Suite 3: --runtime validation +# ============================================================ + +printf "Suite 3: --runtime validation\n" + +assert_exit "valid runtime claude" 0 sh "$SETUP" --ai --runtime claude +rm -f "$REPO_ROOT/.agents/.agentic-os-setup-context.json" + +assert_exit "valid runtime multi" 0 sh "$SETUP" --ai --runtime claude,cursor,cline,antigravity +rm -f "$REPO_ROOT/.agents/.agentic-os-setup-context.json" + +assert_exit "invalid runtime errors" 1 sh "$SETUP" --ai --runtime invalid +assert_exit "partial invalid errors" 1 sh "$SETUP" --ai --runtime claude,bad +assert_output_contains "invalid shows valid list" "Valid runtimes" sh "$SETUP" --ai --runtime bad + +echo "" + +# ============================================================ +# Test Suite 4: --remove +# ============================================================ + +printf "Suite 4: --remove\n" + +assert_exit "remove with no manifest exits 0" 0 sh "$SETUP" --remove +assert_output_contains "remove says no installation" "No agentic-os installation" sh "$SETUP" --remove + +# Test remove with a manifest +FIXTURE_DIR="$RESULTS/remove-test" +mkdir -p "$FIXTURE_DIR/.agents" +echo "test content" > "$FIXTURE_DIR/test-file.md" +printf '{"files":[{"path":"test-file.md","created_at":"2026-01-01","content_hash":"sha256:abc"}]}' > "$FIXTURE_DIR/.agents/.agentic-os-manifest.json" + +sh "$SETUP" --remove --target "$FIXTURE_DIR" > /dev/null 2>&1 +assert_file_not_exists "remove deletes tracked file" "$FIXTURE_DIR/test-file.md" +assert_file_not_exists "remove deletes manifest" "$FIXTURE_DIR/.agents/.agentic-os-manifest.json" + +rm -rf "$FIXTURE_DIR" + +echo "" + +# ============================================================ +# Test Suite 5: --target +# ============================================================ + +printf "Suite 5: --target\n" + +assert_exit "target with valid dir" 0 sh "$SETUP" --ai --runtime claude --target "$REPO_ROOT/examples/uj-3-flask-simple" +rm -f "$REPO_ROOT/examples/uj-3-flask-simple/.agents/.agentic-os-setup-context.json" +rmdir "$REPO_ROOT/examples/uj-3-flask-simple/.agents" 2>/dev/null || true + +assert_exit "target with invalid dir errors" 1 sh "$SETUP" --ai --target /nonexistent +assert_output_contains "target error message" "does not exist" sh "$SETUP" --ai --target /nonexistent + +echo "" + +# ============================================================ +# Test Suite 6: --auto +# ============================================================ + +printf "Suite 6: --auto\n" + +assert_exit "auto without runtime errors" 1 sh "$SETUP" --ai --auto +assert_output_contains "auto error says requires runtime" "requires explicit --runtime" sh "$SETUP" --ai --auto + +assert_exit "auto with runtime succeeds" 0 sh "$SETUP" --ai --auto --runtime claude +rm -f "$REPO_ROOT/.agents/.agentic-os-setup-context.json" + +# Verify context bridge has auto: true +sh "$SETUP" --ai --auto --runtime claude > /dev/null 2>&1 +if grep -q '"auto": true' "$REPO_ROOT/.agents/.agentic-os-setup-context.json"; then + PASS=$((PASS + 1)) + TOTAL=$((TOTAL + 1)) + printf " PASS: context bridge contains auto: true\n" +else + FAIL=$((FAIL + 1)) + TOTAL=$((TOTAL + 1)) + printf " FAIL: context bridge missing auto: true\n" +fi +rm -f "$REPO_ROOT/.agents/.agentic-os-setup-context.json" + +echo "" + +# ============================================================ +# Test Suite 7: Flag combinations +# ============================================================ + +printf "Suite 7: Flag combinations\n" + +assert_exit "ai + dry-run + runtime" 0 sh "$SETUP" --ai --dry-run --runtime claude +rm -f "$REPO_ROOT/.agents/.agentic-os-setup-context.json" + +assert_exit "ai + auto + runtime + target" 0 sh "$SETUP" --ai --auto --runtime cursor --target "$REPO_ROOT/examples/uj-1-node-monorepo" +rm -f "$REPO_ROOT/examples/uj-1-node-monorepo/.agents/.agentic-os-setup-context.json" +rmdir "$REPO_ROOT/examples/uj-1-node-monorepo/.agents" 2>/dev/null || true + +assert_exit "ai + auto + runtime + dry-run" 0 sh "$SETUP" --ai --auto --runtime claude --dry-run +rm -f "$REPO_ROOT/.agents/.agentic-os-setup-context.json" + +assert_exit "unknown flag errors" 1 sh "$SETUP" --bogus + +echo "" + +# ============================================================ +# Summary +# ============================================================ + +printf "============================================================\n" +printf "Results: %d/%d passed" "$PASS" "$TOTAL" +if [ "$FAIL" -gt 0 ]; then + printf " (%d FAILED)\n" "$FAIL" + printf "See: %s/failures.log\n" "$RESULTS" + # Write summary report + printf "FAIL: %d/%d passed (%d failed) — %s\n" "$PASS" "$TOTAL" "$FAIL" "$(date)" > "$RESULTS/report.txt" + exit 1 +else + printf " (all passed)\n" + # Write summary report + printf "PASS: %d/%d passed — %s\n" "$PASS" "$TOTAL" "$(date)" > "$RESULTS/report.txt" + exit 0 +fi From adffeb96611cb4cc4445f196a0c79a3244a93029 Mon Sep 17 00:00:00 2001 From: Mike Lekar Date: Mon, 29 Jun 2026 16:00:02 +0300 Subject: [PATCH 2/3] =?UTF-8?q?feat:=20lean=20AGENTS.md=20generation=20?= =?UTF-8?q?=E2=80=94=20progressive=20disclosure=20+=20context=20budget?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The agentic-os-setup skill instructed the AI to generate a "complete operational manual" inline in AGENTS.md, contradicting the repo's own progressive-disclosure principle and producing a fat always-on file that burns tokens every turn and can overflow the runtime context-file cap. - SKILL.md: invert the AGENTS.md generation rule — keep always-on RULES inline, emit step-by-step PROCEDURES as on-demand skills (task-management, orchestration-model). Add a Context Budget rule (~10k char target, ~20k hard cap, relocate-not-delete). Update Complex tier expectations and Write Sequence to create + manifest + gitignore the emitted skill packs (privacy/removal coverage). Add an MCP "on-demand, not all up front" note for the integration tool surface. - templates/context-budget.md: new keep-inline-vs-emit-as-skill rubric template. - examples/complex-output.md: demonstrate the split across all four runtimes (claude, cursor, cline, antigravity) — lean AGENTS.md managed block + emitted task-management skill + per-runtime companion files. - README.md: align the Memory Stack section with progressive disclosure. Verified: validate_skills.py (no new failures; resolves 2 prior), test_content.py 24/24, skill evals 6/6, routing evals 5/5, eval-case validation pass. --- .agents/skills/agentic-os-setup/SKILL.md | 135 ++++++++---- .../examples/complex-output.md | 196 ++++++++++-------- .../templates/context-budget.md | 88 ++++++++ README.md | 9 +- 4 files changed, 298 insertions(+), 130 deletions(-) create mode 100644 .agents/skills/agentic-os-setup/templates/context-budget.md diff --git a/.agents/skills/agentic-os-setup/SKILL.md b/.agents/skills/agentic-os-setup/SKILL.md index 73de62c..3629c67 100644 --- a/.agents/skills/agentic-os-setup/SKILL.md +++ b/.agents/skills/agentic-os-setup/SKILL.md @@ -40,56 +40,91 @@ Check for an existing manifest at `.agents/.agentic-os-manifest.json`: `setup.sh` has already handled the "dumb" copying: directories, BACKLOG.md, Workflows/, .agents/skills/, symlinks, .gitignore template. Your job is the smart inference and generation: -### 1. Create or update AGENTS.md +### 1. Create or update AGENTS.md (lean, always-on rules ONLY) -If `AGENTS.md` does NOT exist: generate a **complete** AGENTS.md that combines: +AGENTS.md is loaded into the model's context on **every single turn**. Treat it as a +strict budget, not a dumping ground. The framework's headline principle is progressive +disclosure: keep durable RULES always-on in AGENTS.md, and move step-by-step PROCEDURES +into on-demand skills under `.agents/skills/` that load only when invoked. Generating a +fat "complete operational manual" inline is an anti-pattern — it burns tokens every turn +and, on larger repos, overflows the runtime's context-file cap (commonly ~20,000 chars, +after which the middle is silently truncated). -**A) All standard agentic-os behavioral instructions** (these are NOT optional — they make the AI useful): +See `templates/context-budget.md` for the full keep-inline-vs-emit-as-skill rubric. + +If `AGENTS.md` does NOT exist: generate a **lean** AGENTS.md. + +**A) KEEP INLINE in AGENTS.md (always-on rules — these make the AI safe and on-rails):** - How to Work With Files (read, write, list, search patterns) -- Task File Format (full YAML frontmatter template: title, category, priority, status, dates, resource_refs) -- Priority Levels — MUST use P0/P1/P2/P3 format exactly: +- Scope boundaries / isolation rules between domains (repo-specific) +- Cross-reference rules between related folders (repo-specific) +- Naming standards (repo-specific patterns detected per domain) +- Verification Discipline (identify → run → verify → only then claim done) +- Interaction Style (direct, batch questions, never delete user content) +- Writing Style Guidelines (avoid cliches, be direct and concise) +- Priority Levels reference — MUST use P0/P1/P2/P3 format exactly: - **P0**: Critical/urgent, must do THIS WEEK (max 3 recommended) - **P1**: Important, has deadlines, affects others (max 5 recommended) - **P2**: Normal priority, can be scheduled (default) - **P3**: Low priority, nice-to-have -- Backlog Processing Workflow (step-by-step: read → gather context → dedup check → clarify → create → summarize) -- Daily Guidance Workflow (read tasks → filter active → read goals → recommend focus → flag blocked) -- Goals Alignment rules (tie tasks to goals, flag orphan tasks) -- Skills Reference table (categorized: planning, building, analysis, research, decisions, strategy, meetings, stakeholders) -- Skill Routing Policy (execution-first: small task → direct edit, medium → plan+tdd, large → prd+plan+tdd) -- Workflows Reference table (prompt → workflow file mapping) -- Helpful Prompts section (examples: "Show my P0 and P1 tasks", "List blocked tasks", "Archive completed tasks", "Create an eval for this session") -- Subagent Delegation patterns (when to use, when not to, delegation order, output contract) -- Verification Discipline (identify → run → verify → only then claim done) -- Interaction Style (direct, batch questions, never delete user content) -- Session Evals (when to create, eval workflow steps) -- Maintenance Tasks — MUST include ALL of these: - - Prune completed tasks (>30 days old → archive) - - Check priority distribution (warn if >3 P0 or >5 P1) - - Update AGENTS.md (when learning something important about user preferences or workflow, suggest adding it here) - - Review evals (weekly, apply learnings) -- Writing Style Guidelines (avoid cliches, be direct and concise) - -**B) Repo-specific customizations** (discovered during scanning): -- **Workspace layout** — the ACTUAL directory structure two levels deep -- **Task categories** — derived from concern domains found (not generic — use #devex-platform, #access-management, etc.) -- **Scope boundaries** — real isolation rules between domains -- **Cross-references** — real linkage rules between related folders -- **Naming standards** — real patterns detected in each domain - -The workspace layout should go **two levels deep** for major directories: +- A single **Skills & Workflows reference table** (trigger phrase → which skill/workflow + to load). This is the index that makes progressive disclosure work. +- A 2–3 line summary of any load-bearing **mandate** (e.g. an orchestration/sub-agent + model). Keep the mandate summary inline even though its detail moves to a skill — + otherwise the rule silently stops applying on turns when the skill isn't loaded. + +**B) EMIT AS ON-DEMAND SKILLS (procedures — write each as `.agents/skills//SKILL.md`, +NOT inline in AGENTS.md):** +- `task-management` — Task File Format (full YAML frontmatter template), Backlog + Processing Workflow, Daily Guidance Workflow, Goals Alignment rules, Session Evals, + Maintenance Tasks (prune >30d, priority-distribution check >3 P0 / >5 P1, review evals), + Helpful Prompts. +- `orchestration-model` (ONLY if a delegation/sub-agent mandate applies, and `_bmad/` is + NOT present — see Framework Coexistence) — Subagent Delegation patterns: when to use, + when not to, delegation order, output contract, worked examples. + +Each emitted skill MUST be a valid skill pack: YAML frontmatter with `name` (matching its +folder) and a trigger-bearing `description`, a `## When to Use` and `## When Not to Use` +section, and a clear numbered process section. Reference these emitted skills from the +AGENTS.md Skills & Workflows table by trigger phrase. Add every emitted skill file to the +manifest and (unless tracking) the gitignore managed block, exactly like other generated +files — see Write Protocol. + +**C) Repo-specific customizations** (discovered during scanning, folded into the inline +rules above): +- **Workspace layout** — the ACTUAL directory structure, compact. Prefer a flat bullet + list over a deep ASCII tree; go two levels deep only for the major concern domains. +- **Task categories** — derived from concern domains found (not generic — use + `#devex-platform`, `#access-management`, etc.) + +Compact workspace-layout example (bullets, two levels deep for major dirs only): ``` -docs/workitems/ — Cross-project work items (ZSP, CI, Crossplane) -docs/workitems/devex/ — DevEx Platform project (130+ items, ADO-synced) -docs/designs/ — Architecture decisions and designs - ├── access-management/ — ZSP AWS access model - ├── github-jira-migration-plan/ - └── ... (11 initiatives) +- docs/workitems/ — cross-project work items (ZSP, CI, Crossplane); + docs/workitems/devex/ — DevEx Platform (130+ items, ADO-synced, PRIMARY) +- docs/designs// — architecture/designs (access-management, + github-jira-migration-plan, … 11 initiatives) ``` -**Critical:** The behavioral sections (A) must be COMPLETE — don't summarize them into one-liners. The repo-specific sections (B) replace the generic equivalents from the template. The result should be a full operational manual for the AI, not a summary. +**Critical:** AGENTS.md is rules + an index, NOT a manual. The behavioral procedures live +in emitted skills (B) and load on demand. The repo-specific rules (C) replace the generic +template equivalents. Verify the result against the context budget below before writing. + +If `AGENTS.md` already exists: extend it with a managed block containing only the always-on +rules (scope isolation, cross-references, naming, and the Skills & Workflows index) — same +as Antigravity adapter behavior. Still emit the procedure skills (B) separately. + +### 1b. Context Budget (enforce before writing AGENTS.md) -If `AGENTS.md` already exists: extend it with a managed block containing agentic-os behavioral rules (scope isolation, cross-references, etc.) — same as Antigravity adapter behavior. +- **Target:** generated AGENTS.md ≤ ~10,000 chars (≈ 2,500 tokens). Hard ceiling: the + runtime context-file cap, commonly ~20,000 chars — never generate above it, since + content past the cap is head/tail-truncated and the middle is lost. +- **If inline content would exceed the target:** move the lowest-priority sections to + on-demand skills (per the B list and `templates/context-budget.md`) and leave a one-line + pointer in the Skills & Workflows table. Do not shrink by deleting rules — relocate them. +- **Tier coupling:** Simple/Multi repos rarely approach the budget. **Complex** repos and + any repo with a framework (`_bmad/`) MUST split procedures into skills — never inline the + full manual. State the resulting AGENTS.md char count in the proposal so the user can see + it stayed within budget. ### 2. Create or update AI tool wrapper files @@ -221,7 +256,7 @@ Based on the classified tier and detected signals, assemble a configuration prop | Zero | Nothing — repo is empty. Suggest running classic `setup.sh` instead. | | Simple | 1 config file per targeted runtime. Minimal: basic project context, no persona routing. | | Multi | Config files per runtime + AGENTS.md with persona definitions. Persona routing, scope isolation. | -| Complex | Full output: AGENTS.md, GOALS.md (if none exists), config files with persona routing, scope isolation, cross-reference enforcement, quality gates. | +| Complex | Lean AGENTS.md (always-on rules + Skills & Workflows index), GOALS.md (if none exists), emitted on-demand skills for procedures (task-management, and orchestration-model unless `_bmad/` present), config files with persona routing, scope isolation, cross-reference enforcement, quality gates. AGENTS.md MUST stay within the context budget — procedures go to skills, never inline. | ### Assembly Process @@ -247,6 +282,21 @@ When other AI configs exist (.cursor/rules/, CLAUDE.md, .clinerules): - Generate agentic-os rules as additive companion files (see adapter specs for pre-existing file behavior) - Check for glob collisions with existing .cursor/rules/ before proposing new ones +## MCP Integrations — On-Demand, Not All Up Front + +MCP servers (Slack, Linear, Google Calendar, Atlassian, Granola under `System/integrations/`) +each load their full tool schemas into the model's context. A handful of integrations can +add tens of thousands of tokens per turn — the same context-budget problem as a fat +AGENTS.md, but in the tool surface. + +When proposing or documenting MCP integrations: +- Recommend enabling only the integrations the repo actually uses, not the whole set. +- Note that an integration with a large or recursive tool schema is the biggest per-turn + offender — suggest enabling it on demand for the sessions that need it, then disabling it. +- Keep domain-scoped servers scoped (e.g. restrict to the specific tool domain rather than + exposing all of a server's tools) when the runtime supports it. +- Tool-list changes typically take effect on a fresh session, not mid-conversation. + ## Diff Preview Protocol All proposed changes MUST be presented as unified diffs before any files are written. @@ -375,8 +425,9 @@ After the user approves the proposal (fully or selectively), write files followi ### Write Sequence 1. Create approved configuration files (CLAUDE.md, .cursor/rules/*.mdc, .clinerules, AGENTS.md extension) -2. Write the manifest (`.agents/.agentic-os-manifest.json`) -3. Update .gitignore (unless `--track` was specified) +2. Create approved emitted skill packs (`.agents/skills//SKILL.md` + `agents/openai.yaml` for each procedure skill split out of AGENTS.md) +3. Write the manifest (`.agents/.agentic-os-manifest.json`) — list every config file AND every emitted skill file +4. Update .gitignore (unless `--track` was specified) — include the emitted skill paths so privacy/removal covers them too ### Manifest Schema diff --git a/.agents/skills/agentic-os-setup/examples/complex-output.md b/.agents/skills/agentic-os-setup/examples/complex-output.md index 73137f7..38d1479 100644 --- a/.agents/skills/agentic-os-setup/examples/complex-output.md +++ b/.agents/skills/agentic-os-setup/examples/complex-output.md @@ -2,52 +2,124 @@ ## Scenario -A multi-concern monorepo with `Designs/`, `Operations/`, `Team-Workitems/`, `Infrastructure/`, and `docs/` at root. Existing `.cursor/rules/` (files 800-805), existing AGENTS.md. Two team indicators. Cross-references between Operations and Designs. +A multi-concern monorepo with `Designs/`, `Operations/`, `Team-Workitems/`, `Infrastructure/`, and `docs/` at root. Existing `.cursor/rules/` (files 800-805), existing AGENTS.md, existing `.clinerules`. Two team indicators. Cross-references between Operations and Designs. -**Detected signals:** .cursor/rules/ (6 files, 800-band), AGENTS.md, 5 concern folders, team indicators, cross-domain references +**Detected signals:** .cursor/rules/ (6 files, 800-band), AGENTS.md, .clinerules, 5 concern folders, team indicators, cross-domain references **Classification:** Complex (5+ concern folders, 4+ AI configs, 2 teams, 2+ cross-refs) -**Runtimes targeted:** claude, cursor, antigravity +**Runtimes targeted:** claude, cursor, cline, antigravity + +## Key principle for Complex tier + +Complex repos accumulate the most rules — so the generated AGENTS.md MUST stay lean +(always-on rules + a Skills & Workflows index) and the step-by-step PROCEDURES are emitted +as on-demand skills under `.agents/skills/`. Never inline the full operational manual; it +overflows the context budget and burns tokens every turn. See `templates/context-budget.md`. ## Expected Output -### File: CLAUDE-agentic-os.md (companion — existing CLAUDE.md untouched) +### File: AGENTS.md (extended via managed block — existing user content preserved above) + +The managed block holds ONLY always-on rules plus the index. Procedures are pointers. ```markdown -# Agentic-OS Configuration + +## Agentic-OS Generated Rules -## Persona Routing +### Workspace Layout +- Designs// — architecture & system design +- Operations/ — process, recruitment, documentation +- Team-Workitems/ — work items (trace to Designs/ via Design-Ref:) +- Infrastructure/ — IaC, deployment, security baselines -- **Architect Mode:** Triggered when editing `/Designs/`. Prioritize structural scalability, system design patterns, and requirements traceability. -- **Operations Mode:** Triggered when editing `/Operations/`. Focus on process efficiency, candidate assessment, and documentation completeness. -- **Engineering Mode:** Triggered when editing `/Infrastructure/`. Focus on reliability, security, and operational readiness. +### Scope Boundaries +| Domain | Isolated From | Rationale | +|--------|--------------|-----------| +| Designs/ | Operations/, Team-Workitems/ | Architecture is independent of HR ops | +| Operations/ | Designs/, Infrastructure/ | Recruitment is independent of design | +| Infrastructure/ | Operations/, Designs/ | IaC has distinct safety requirements | -See AGENTS.md for full persona definitions. +### Cross-References +| Source | Target | Link Format | +|--------|--------|-------------| +| Operations/job-interviews/ | Operations/job-descriptions/ | `Job-ID: jd-*` | +| Team-Workitems/ | Designs/ | `Design-Ref: *` | -## Scope Isolation +### Priority Levels +P0 (this week, max 3) / P1 (deadlines, max 5) / P2 (default) / P3 (nice-to-have) + +### Verification Discipline +Identify what "done" means → run verification → confirm output → only then claim done. + +### Skills & Workflows (load on demand) +| Trigger | Load | +|---------|------| +| "process backlog", task format, daily/weekly, maintenance | task-management skill | +| decomposing or delegating non-trivial work | orchestration-model skill | + + +``` + +### Emitted skill: .agents/skills/task-management/SKILL.md (procedures moved out of AGENTS.md) + +```markdown +--- +name: task-management +description: Task file format, priorities, backlog/daily/weekly/maintenance workflows. Load when creating or triaging tasks, processing the backlog, or doing workspace hygiene. +--- + +# Task & Workflow Management + +## When to Use +Creating/triaging tasks, "process my backlog", daily guidance, weekly review, maintenance. + +## When Not to Use +Simple one-off edits with no task tracking; pure code changes. + +## Task File Format +1. YAML frontmatter: title, category, priority (P0-P3), status, created, due, resource_refs, goal_ref +2. Body + Acceptance Criteria checklist. + +## Backlog Processing +1. Read BACKLOG.md → 2. classify domain → 3. dedup check → 4. clarify → 5. create task files → 6. summarize. -The following domains are isolated — do not cross-reference unless explicitly asked: -- `/Designs/` and `/Operations/` are independent concerns -- `/Infrastructure/` and `/Team-Workitems/` are independent concerns +## Maintenance +- Prune done tasks >30 days. Warn if >3 P0 or >5 P1. Review evals weekly. +``` -## Cross-Reference Rules +A matching `agents/openai.yaml` (name, description, version: 1, invocation.trigger) is emitted alongside each skill so OpenAI-style runtimes can route to it. -- **Operations/ → Designs/**: Interview files must reference a valid job description via `Job-ID:` frontmatter field -- **Team-Workitems/ → Designs/**: Work items should trace to design documents via `Design-Ref:` field +### File: CLAUDE-agentic-os.md (companion — existing CLAUDE.md untouched) -## Naming Conventions +```markdown +# Agentic-OS Configuration -### Operations/job-interviews/ -- Candidate files: `candidate_[first-name]-[last-name].md` +This file supplements the existing CLAUDE.md with agentic-os configuration. -### Team-Workitems/ -- Work items: `[priority]-[short-description].md` +## Persona Routing +- **Architect Mode** (editing `/Designs/`): structural scalability, requirements traceability. +- **Operations Mode** (editing `/Operations/`): process efficiency, documentation completeness. +- **Infrastructure Mode** (editing `/Infrastructure/`): reliability, security, operational readiness. -## Quality Gates +See AGENTS.md for scope boundaries and the Skills & Workflows index. -Before completing work, verify: -- **Linting**: `make lint` -- **Tests**: `make test` -- **Cross-references**: Verify linked documents exist +## Skills +Canonical skills live under `.agents/skills/*/SKILL.md`. To run one, read its SKILL.md and follow the instructions. Procedures (task-management, orchestration-model) load on demand — they are not duplicated here. +``` + +### File: .clinerules-agentic-os (companion — existing .clinerules untouched) + +```markdown +# Agentic-OS Rules + +## Scope Isolation +- When in /Designs/: do not suggest content from /Operations/ or /Infrastructure/. +- When in /Operations/: do not suggest content from /Designs/ or /Team-Workitems/. +- When in /Infrastructure/: do not suggest content from /Operations/ or /Designs/. + +## Procedures +Task format, backlog, daily/weekly, and maintenance procedures are defined in the +task-management skill (`.agents/skills/task-management/SKILL.md`). Load it when doing that +work rather than duplicating the steps here. ``` ### File: .cursor/rules/806-agentic-os-personas.mdc @@ -62,7 +134,7 @@ alwaysApply: true When working in Designs/: - Prioritize structural scalability and system design metrics -- Reference AGENTS.md for architecture persona guidelines +- Reference AGENTS.md for architecture persona guidelines and the Skills & Workflows index - Cross-reference parent blueprints for requirements traceability - Do not suggest patterns from Operations/ or Infrastructure/ ``` @@ -79,72 +151,24 @@ alwaysApply: true When working in Operations/: - Do not read or suggest content from Designs/ or Infrastructure/ -- Keep completions scoped to HR/recruitment conventions When working in Designs/: - Do not read or suggest content from Operations/ or Team-Workitems/ -- Keep completions scoped to architecture patterns When working in Infrastructure/: - Do not read or suggest content from Operations/ or Designs/ -- Keep completions scoped to IaC and deployment patterns -``` - -### File: AGENTS.md (extended via managed block — existing content preserved above) - -```markdown - -## Agentic-OS Generated Rules - -### Personas - -#### Architect -**Scope:** `/Designs/` -**Focus:** System design, scalability, requirements traceability -**Behavioral rules:** -- Prioritize structural patterns over quick fixes -- Reference existing blueprints before proposing new structures -- Validate against design principles in docs/ - -#### Operations Specialist -**Scope:** `/Operations/` -**Focus:** Process efficiency, documentation completeness, candidate assessment -**Behavioral rules:** -- Follow HR documentation standards -- Enforce cross-reference rules (interviews → job descriptions) -- Maintain naming conventions strictly - -#### Infrastructure Engineer -**Scope:** `/Infrastructure/` -**Focus:** Reliability, security, operational readiness -**Behavioral rules:** -- Validate against security baselines -- Consider blast radius of changes -- Reference runbooks for operational procedures - -### Scope Boundaries - -| Domain | Isolated From | Rationale | -|--------|--------------|-----------| -| Designs/ | Operations/, Team-Workitems/ | Architecture concerns are independent of HR operations | -| Operations/ | Designs/, Infrastructure/ | Recruitment is independent of system design | -| Infrastructure/ | Operations/, Designs/ | IaC has distinct safety requirements | - -### Cross-References - -| Source | Target | Link Format | Rule | -|--------|--------|-------------|------| -| Operations/job-interviews/ | Operations/job-descriptions/ | `Job-ID: jd-*` | Every interview file must link to a valid JD | -| Team-Workitems/ | Designs/ | `Design-Ref: *` | Work items should trace to design docs | - - ``` ## Volume Calibration Complex tier output should be: -- Multiple config files per runtime (personas, isolation, cross-refs may be separate) -- AGENTS.md with full persona definitions and relationship tables -- 50-150 lines per major file -- Comprehensive organizational rules covering personas, isolation, cross-references, and naming -- Cursor rules in separate files by concern (personas, isolation) to avoid glob conflicts +- **Lean AGENTS.md** — always-on rules + Skills & Workflows index ONLY, within the context + budget (≤ ~10,000 chars; never above the runtime cap). State the char count in the proposal. +- **Emitted on-demand skills** for procedures (task-management; orchestration-model unless + `_bmad/` is present). Each is a valid skill pack with frontmatter, When to Use / When Not + to Use, and a numbered process — plus a matching `agents/openai.yaml`. +- Per-runtime config files for all targeted runtimes (claude, cursor, cline, antigravity), + using companion files where a config already exists. +- Cursor rules in separate files by concern (personas, isolation) to avoid glob conflicts. +- Every emitted skill file listed in the manifest and (unless `--track`) the gitignore + managed block, so privacy and `--remove` cover them too. diff --git a/.agents/skills/agentic-os-setup/templates/context-budget.md b/.agents/skills/agentic-os-setup/templates/context-budget.md new file mode 100644 index 0000000..257bd85 --- /dev/null +++ b/.agents/skills/agentic-os-setup/templates/context-budget.md @@ -0,0 +1,88 @@ +# Template: Context Budget + +## Intent + +Keep generated agent-instruction files lean so they cost the fewest tokens per turn while +still encoding every rule the AI needs. Always-on files (AGENTS.md, CLAUDE.md, .clinerules, +the AGENTS.md managed block) are injected into the model's context on **every turn** — so +durable RULES stay inline, and step-by-step PROCEDURES move into on-demand skills that load +only when invoked. This is the framework's progressive-disclosure principle applied to the +files the installer itself generates. + +## Inputs Required + +- `{always_on_rules}`: the rules that must govern every turn (scope isolation, naming, + verification, interaction style, priority levels, the Skills & Workflows index) +- `{procedures}`: the step-by-step workflows that only matter when invoked (task format, + backlog/daily/weekly/maintenance, session evals, delegation patterns, helpful prompts) +- `{mandates}`: any load-bearing behavioral mandate (e.g. an orchestration/sub-agent model) +- `{context_cap}`: the target runtime's context-file size limit (commonly ~20,000 chars) + +## Keep Inline vs Emit as Skill + +| Content | Where it goes | Why | +|---------|---------------|-----| +| File-handling rules, scope isolation, cross-references, naming standards | INLINE (always-on) | Must apply on every edit, regardless of task | +| Verification discipline, interaction & writing style | INLINE (always-on) | Govern how the AI behaves on every turn | +| Priority Levels reference (P0/P1/P2/P3) | INLINE (always-on) | Short; needed whenever priorities are read | +| Skills & Workflows reference table (trigger → skill) | INLINE (always-on) | The index that makes progressive disclosure work | +| Mandate SUMMARY (2-3 lines) | INLINE (always-on) | Rule must still apply when the detail skill isn't loaded | +| Task File Format + full YAML template | EMIT as `task-management` skill | Only needed when creating tasks | +| Backlog / Daily / Weekly / Maintenance workflows | EMIT as `task-management` skill | Procedures, invoked occasionally | +| Session Evals, Helpful Prompts | EMIT as `task-management` skill | Reference material, not per-turn rules | +| Subagent delegation patterns + worked examples | EMIT as `orchestration-model` skill | Bulky; load only when delegating | + +## Output Pattern (lean AGENTS.md skeleton) + +```markdown +# AGENTS.md + +Always-on rules below. Procedures live in on-demand skills (see Skills & Workflows). + +## Workspace Layout +{compact bullet list, two levels deep for major dirs only} + +## How to Work With Files +{read/write/list/search rules} + +## Scope Isolation & Cross-References +{repo-specific boundaries and linkage rules} + +## Naming Standards +{repo-specific patterns} + +## Priority Levels +P0 (this week, max 3) / P1 (deadlines, max 5) / P2 (default) / P3 (nice-to-have) + +## Mandate +{2-3 line summary of any orchestration/delegation model; full detail in the skill} + +## Verification Discipline / Interaction & Writing Style +{always-on behavioral rules} + +## Skills & Workflows +| Trigger phrase | Load | +|----------------|------| +| "process backlog", "daily prep", task work | task-management skill | +| delegating / decomposing non-trivial work | orchestration-model skill | +| ... | ... | +``` + +## Budget Rules + +1. **Target** generated AGENTS.md at ≤ ~10,000 chars (≈ 2,500 tokens). +2. **Never exceed** `{context_cap}` — content past the cap is head/tail-truncated and the + middle is silently dropped, so a fat file loses rules without warning. +3. **If over target:** relocate the lowest-priority sections to on-demand skills and leave + a one-line pointer in the Skills & Workflows table. Relocate, never delete. +4. **Keep mandates inline as summaries** — moving a mandate entirely into a skill means it + stops applying on turns when the skill isn't loaded. +5. **State the resulting char count** in the proposal so the user can confirm it fit. + +## When to Use + +- **Complexity tier:** Multi or Complex (Simple repos rarely approach the budget) +- **Always** when a framework is present (`_bmad/`) — these repos accumulate the most rules + and overflow fastest, so procedures MUST be split into skills +- **Detected signals:** an existing AGENTS.md already near or over the context cap, many + concern domains, or a delegation/orchestration mandate that would otherwise be inlined diff --git a/README.md b/README.md index d68029d..1dddd1e 100644 --- a/README.md +++ b/README.md @@ -183,13 +183,18 @@ Semantics by location: `Tasks/**/*.md` = actionable work, `Knowledge/**/*.md` = ### The Memory Stack ``` -AGENTS.md → Instructions layer (how AI behaves) +AGENTS.md → Instructions layer (always-on RULES only — kept lean) GOALS.md → Priority layer (what matters) Tasks/**/*.md → State layer (current work) Knowledge/**/*.md → Context layer (reference) -.agents/skills/* → Capability layer (how the agent executes specialized workflows) +.agents/skills/* → Capability layer (PROCEDURES — load on demand) ``` +AGENTS.md holds always-on rules and an index; step-by-step procedures live in +`.agents/skills/` and load on demand (progressive disclosure). The AI-assisted setup keeps +generated AGENTS.md within a context budget and emits bulky procedures as on-demand skills +rather than inlining them — so every turn stays cheap. + ### Privacy First Personal operating data stays local (gitignored): From edb4cebac1699d54b9bdd53311306d01ee8421e2 Mon Sep 17 00:00:00 2001 From: Mike Lekar Date: Mon, 29 Jun 2026 16:20:09 +0300 Subject: [PATCH 3/3] test: lock lean-AGENTS.md contract; gitignore eval results; document 4-runtime verification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to the progressive-disclosure change. Adds executable guardrails and real-world test evidence, and stops tracking generated eval output. - tests/test_content.py: new TestContextBudget class (7 assertions) that locks the lean-AGENTS.md contract — the Complex calibration example's managed block must stay within budget, carry a "Skills & Workflows" index, and inline NO procedure sections; SKILL.md must define the context budget and instruct emitting procedures as on-demand skills; the example must cover all four runtimes. Guards against silent regression back to the fat operational manual. 24 -> 31 tests, all pass. - .gitignore: ignore generated eval results (Evals/skills|memory/results/*.json) while keeping the READMEs; untrack the 7 result JSONs that were committed upstream. Mirrors the existing tests/results/ rule — these are run artifacts, not source. - pull-request.md: replace the stale "AGENTS.md = full behavioral instructions" notes with verified results from running the installer against the architect-docs monorepo cloned four times (one runtime each). All four produced a lean AGENTS.md within budget (Claude 5.2k, Cursor 4.8k, Cline 4.2k, Antigravity 4.2k), an emitted task-management skill, correct BMAD persona deferral, and clean per-runtime files — verified on disk. Gate: shell 29/29, python 31/31, skill evals 6/6, routing 5/5. --- .gitignore | 5 + .../20260213T141841Z-memory-impact.json | 94 -------------- .../results/20260212T171727Z-fixture.json | 121 ------------------ .../results/20260212T171746Z-fixture.json | 121 ------------------ .../results/20260212T171758Z-fixture.json | 121 ------------------ .../results/20260212T173258Z-fixture.json | 121 ------------------ .../results/20260213T141834Z-fixture.json | 121 ------------------ .../results/20260213T141834Z-routing.json | 92 ------------- .../pull-request.md | 46 ++++--- tests/test_content.py | 83 ++++++++++++ 10 files changed, 119 insertions(+), 806 deletions(-) delete mode 100644 Evals/memory/results/20260213T141841Z-memory-impact.json delete mode 100644 Evals/skills/results/20260212T171727Z-fixture.json delete mode 100644 Evals/skills/results/20260212T171746Z-fixture.json delete mode 100644 Evals/skills/results/20260212T171758Z-fixture.json delete mode 100644 Evals/skills/results/20260212T173258Z-fixture.json delete mode 100644 Evals/skills/results/20260213T141834Z-fixture.json delete mode 100644 Evals/skills/results/20260213T141834Z-routing.json diff --git a/.gitignore b/.gitignore index 84bd631..86f4ec0 100644 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,8 @@ Thumbs.db # Test results (generated output, not tracked) tests/results/ + +# Eval results (generated output, not tracked — keep READMEs) +Evals/skills/results/*.json +Evals/memory/results/*.json +!Evals/**/README.md diff --git a/Evals/memory/results/20260213T141841Z-memory-impact.json b/Evals/memory/results/20260213T141841Z-memory-impact.json deleted file mode 100644 index 58b730f..0000000 --- a/Evals/memory/results/20260213T141841Z-memory-impact.json +++ /dev/null @@ -1,94 +0,0 @@ -{ - "timestamp_utc": "20260213T141841Z", - "summary": { - "total_cases": 3, - "passed_cases": 3, - "pass_rate": 1.0, - "min_pass_rate": 1.0 - }, - "results": [ - { - "id": "daily-focus-goal-alignment", - "input": "What should I work on today?", - "baseline_response": "Work on any available high-priority task.", - "memory_search_response": "Prioritize unblocked P0/P1 tasks aligned to GOALS.md, and flag blocked work with next steps.", - "expected_when_enabled": [ - "aligned to goals", - "unblocked", - "blocked work" - ], - "expected_missing_in_baseline": [ - "aligned to goals", - "blocked work" - ], - "enabled_hits": [ - "aligned to goals", - "unblocked", - "blocked work" - ], - "enabled_misses": [], - "baseline_missing_ok": [ - "aligned to goals", - "blocked work" - ], - "baseline_missing_fail": [], - "passed": true - }, - { - "id": "backlog-processing-context-lookup", - "input": "Process my backlog.", - "baseline_response": "Convert backlog items into tasks.", - "memory_search_response": "Read Knowledge docs for context, detect duplicates against Tasks, then create scoped tasks with priorities.", - "expected_when_enabled": [ - "knowledge docs", - "duplicates", - "priorities" - ], - "expected_missing_in_baseline": [ - "duplicates", - "knowledge docs" - ], - "enabled_hits": [ - "knowledge docs", - "duplicates", - "priorities" - ], - "enabled_misses": [], - "baseline_missing_ok": [ - "duplicates", - "knowledge docs" - ], - "baseline_missing_fail": [], - "passed": true - }, - { - "id": "recommend-top-three", - "input": "Give me today's top three tasks.", - "baseline_response": "Here are three tasks to work on.", - "memory_search_response": "Select top three based on priority, due date pressure, and GOALS alignment, then include verification evidence requirements.", - "expected_when_enabled": [ - "priority", - "due date", - "goals alignment", - "verification evidence" - ], - "expected_missing_in_baseline": [ - "goals alignment", - "verification evidence" - ], - "enabled_hits": [ - "priority", - "due date", - "goals alignment", - "verification evidence" - ], - "enabled_misses": [], - "baseline_missing_ok": [ - "goals alignment", - "verification evidence" - ], - "baseline_missing_fail": [], - "passed": true - } - ] -} diff --git a/Evals/skills/results/20260212T171727Z-fixture.json b/Evals/skills/results/20260212T171727Z-fixture.json deleted file mode 100644 index 24da4d7..0000000 --- a/Evals/skills/results/20260212T171727Z-fixture.json +++ /dev/null @@ -1,121 +0,0 @@ -{ - "timestamp_utc": "20260212T171727Z", - "provider": "fixture", - "threshold": 0.6, - "min_pass_rate": 1.0, - "summary": { - "total_cases": 6, - "passed_cases": 3, - "pass_rate": 0.5 - }, - "results": [ - { - "skill": "tdd", - "case_id": "tdd-code-first-request", - "passed": true, - "checks": [ - { - "expected": "enforces failing test first", - "score": 0.75, - "passed": true - }, - { - "expected": "uses red green refactor sequence", - "score": 0.8, - "passed": true - } - ], - "response": "Use test-first TDD: start with a failing test, then implement the minimum code to pass, then refactor in a red-green-refactor sequence." - }, - { - "skill": "tdd", - "case_id": "tdd-manual-test-only", - "passed": true, - "checks": [ - { - "expected": "rejects manual test as substitute", - "score": 0.6, - "passed": true - }, - { - "expected": "requires test-first workflow", - "score": 0.75, - "passed": true - } - ], - "response": "Manual testing is not a substitute for test-first workflow. Write a failing automated test first, then implement and refactor." - }, - { - "skill": "verification", - "case_id": "verification-no-evidence-claim", - "passed": false, - "checks": [ - { - "expected": "demands fresh verification evidence", - "score": 0.75, - "passed": true - }, - { - "expected": "does not claim completion without command output", - "score": 0.286, - "passed": false - } - ], - "response": "I cannot mark this complete without fresh verification evidence. Run the required commands and share output before claiming done." - }, - { - "skill": "verification", - "case_id": "verification-partial-check", - "passed": false, - "checks": [ - { - "expected": "rejects incomplete verification", - "score": 0.333, - "passed": false - }, - { - "expected": "asks for required command(s) tied to claim", - "score": 0.5, - "passed": false - } - ], - "response": "Lint alone is not sufficient verification. Run the required test and build commands tied to the completion claim." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-multi-step-migration", - "passed": true, - "checks": [ - { - "expected": "provides bite-sized executable steps", - "score": 0.8, - "passed": true - }, - { - "expected": "includes explicit verification checks", - "score": 0.75, - "passed": true - } - ], - "response": "I will provide bite-sized executable steps with explicit verification checks after each migration step." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-overly-vague", - "passed": false, - "checks": [ - { - "expected": "adds structure and concrete sequence", - "score": 0.8, - "passed": true - }, - { - "expected": "avoids vague generic planning", - "score": 0.5, - "passed": false - } - ], - "response": "I will add concrete structure and a clear sequence of actions rather than a vague generic plan." - } - ] -} diff --git a/Evals/skills/results/20260212T171746Z-fixture.json b/Evals/skills/results/20260212T171746Z-fixture.json deleted file mode 100644 index 1fd87f5..0000000 --- a/Evals/skills/results/20260212T171746Z-fixture.json +++ /dev/null @@ -1,121 +0,0 @@ -{ - "timestamp_utc": "20260212T171746Z", - "provider": "fixture", - "threshold": 0.6, - "min_pass_rate": 1.0, - "summary": { - "total_cases": 6, - "passed_cases": 5, - "pass_rate": 0.833 - }, - "results": [ - { - "skill": "tdd", - "case_id": "tdd-code-first-request", - "passed": true, - "checks": [ - { - "expected": "enforces failing test first", - "score": 0.75, - "passed": true - }, - { - "expected": "uses red green refactor sequence", - "score": 0.8, - "passed": true - } - ], - "response": "Use test-first TDD: start with a failing test, then implement the minimum code to pass, then refactor in a red-green-refactor sequence." - }, - { - "skill": "tdd", - "case_id": "tdd-manual-test-only", - "passed": true, - "checks": [ - { - "expected": "rejects manual test as substitute", - "score": 0.6, - "passed": true - }, - { - "expected": "requires test-first workflow", - "score": 0.75, - "passed": true - } - ], - "response": "Manual testing is not a substitute for test-first workflow. Write a failing automated test first, then implement and refactor." - }, - { - "skill": "verification", - "case_id": "verification-no-evidence-claim", - "passed": true, - "checks": [ - { - "expected": "demands fresh verification evidence", - "score": 0.75, - "passed": true - }, - { - "expected": "does not claim completion without command output", - "score": 0.857, - "passed": true - } - ], - "response": "I demand fresh verification evidence and will not claim completion without command output." - }, - { - "skill": "verification", - "case_id": "verification-partial-check", - "passed": false, - "checks": [ - { - "expected": "rejects incomplete verification", - "score": 0.667, - "passed": true - }, - { - "expected": "asks for required command(s) tied to claim", - "score": 0.5, - "passed": false - } - ], - "response": "I reject incomplete verification. Please run the required commands tied to the claim." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-multi-step-migration", - "passed": true, - "checks": [ - { - "expected": "provides bite-sized executable steps", - "score": 0.8, - "passed": true - }, - { - "expected": "includes explicit verification checks", - "score": 0.75, - "passed": true - } - ], - "response": "I will provide bite-sized executable steps with explicit verification checks after each migration step." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-overly-vague", - "passed": true, - "checks": [ - { - "expected": "adds structure and concrete sequence", - "score": 0.8, - "passed": true - }, - { - "expected": "avoids vague generic planning", - "score": 0.75, - "passed": true - } - ], - "response": "I will add structure and concrete sequence and avoid vague generic planning." - } - ] -} diff --git a/Evals/skills/results/20260212T171758Z-fixture.json b/Evals/skills/results/20260212T171758Z-fixture.json deleted file mode 100644 index 92d90b8..0000000 --- a/Evals/skills/results/20260212T171758Z-fixture.json +++ /dev/null @@ -1,121 +0,0 @@ -{ - "timestamp_utc": "20260212T171758Z", - "provider": "fixture", - "threshold": 0.6, - "min_pass_rate": 1.0, - "summary": { - "total_cases": 6, - "passed_cases": 6, - "pass_rate": 1.0 - }, - "results": [ - { - "skill": "tdd", - "case_id": "tdd-code-first-request", - "passed": true, - "checks": [ - { - "expected": "enforces failing test first", - "score": 0.75, - "passed": true - }, - { - "expected": "uses red green refactor sequence", - "score": 0.8, - "passed": true - } - ], - "response": "Use test-first TDD: start with a failing test, then implement the minimum code to pass, then refactor in a red-green-refactor sequence." - }, - { - "skill": "tdd", - "case_id": "tdd-manual-test-only", - "passed": true, - "checks": [ - { - "expected": "rejects manual test as substitute", - "score": 0.6, - "passed": true - }, - { - "expected": "requires test-first workflow", - "score": 0.75, - "passed": true - } - ], - "response": "Manual testing is not a substitute for test-first workflow. Write a failing automated test first, then implement and refactor." - }, - { - "skill": "verification", - "case_id": "verification-no-evidence-claim", - "passed": true, - "checks": [ - { - "expected": "demands fresh verification evidence", - "score": 0.75, - "passed": true - }, - { - "expected": "does not claim completion without command output", - "score": 0.857, - "passed": true - } - ], - "response": "I demand fresh verification evidence and will not claim completion without command output." - }, - { - "skill": "verification", - "case_id": "verification-partial-check", - "passed": true, - "checks": [ - { - "expected": "rejects incomplete verification", - "score": 1.0, - "passed": true - }, - { - "expected": "asks for required command(s) tied to claim", - "score": 0.875, - "passed": true - } - ], - "response": "This rejects incomplete verification and asks for required command tied to claim." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-multi-step-migration", - "passed": true, - "checks": [ - { - "expected": "provides bite-sized executable steps", - "score": 0.8, - "passed": true - }, - { - "expected": "includes explicit verification checks", - "score": 0.75, - "passed": true - } - ], - "response": "I will provide bite-sized executable steps with explicit verification checks after each migration step." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-overly-vague", - "passed": true, - "checks": [ - { - "expected": "adds structure and concrete sequence", - "score": 0.8, - "passed": true - }, - { - "expected": "avoids vague generic planning", - "score": 0.75, - "passed": true - } - ], - "response": "I will add structure and concrete sequence and avoid vague generic planning." - } - ] -} diff --git a/Evals/skills/results/20260212T173258Z-fixture.json b/Evals/skills/results/20260212T173258Z-fixture.json deleted file mode 100644 index 22ae40c..0000000 --- a/Evals/skills/results/20260212T173258Z-fixture.json +++ /dev/null @@ -1,121 +0,0 @@ -{ - "timestamp_utc": "20260212T173258Z", - "provider": "fixture", - "threshold": 0.6, - "min_pass_rate": 1.0, - "summary": { - "total_cases": 6, - "passed_cases": 6, - "pass_rate": 1.0 - }, - "results": [ - { - "skill": "tdd", - "case_id": "tdd-code-first-request", - "passed": true, - "checks": [ - { - "expected": "enforces failing test first", - "score": 0.75, - "passed": true - }, - { - "expected": "uses red green refactor sequence", - "score": 0.8, - "passed": true - } - ], - "response": "Use test-first TDD: start with a failing test, then implement the minimum code to pass, then refactor in a red-green-refactor sequence." - }, - { - "skill": "tdd", - "case_id": "tdd-manual-test-only", - "passed": true, - "checks": [ - { - "expected": "rejects manual test as substitute", - "score": 0.6, - "passed": true - }, - { - "expected": "requires test-first workflow", - "score": 0.75, - "passed": true - } - ], - "response": "Manual testing is not a substitute for test-first workflow. Write a failing automated test first, then implement and refactor." - }, - { - "skill": "verification", - "case_id": "verification-no-evidence-claim", - "passed": true, - "checks": [ - { - "expected": "demands fresh verification evidence", - "score": 0.75, - "passed": true - }, - { - "expected": "does not claim completion without command output", - "score": 0.857, - "passed": true - } - ], - "response": "I demand fresh verification evidence and will not claim completion without command output." - }, - { - "skill": "verification", - "case_id": "verification-partial-check", - "passed": true, - "checks": [ - { - "expected": "rejects incomplete verification", - "score": 1.0, - "passed": true - }, - { - "expected": "asks for required command(s) tied to claim", - "score": 0.875, - "passed": true - } - ], - "response": "This rejects incomplete verification and asks for required command tied to claim." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-multi-step-migration", - "passed": true, - "checks": [ - { - "expected": "provides bite-sized executable steps", - "score": 0.8, - "passed": true - }, - { - "expected": "includes explicit verification checks", - "score": 0.75, - "passed": true - } - ], - "response": "I will provide bite-sized executable steps with explicit verification checks after each migration step." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-overly-vague", - "passed": true, - "checks": [ - { - "expected": "adds structure and concrete sequence", - "score": 0.8, - "passed": true - }, - { - "expected": "avoids vague generic planning", - "score": 0.75, - "passed": true - } - ], - "response": "I will add structure and concrete sequence and avoid vague generic planning." - } - ] -} diff --git a/Evals/skills/results/20260213T141834Z-fixture.json b/Evals/skills/results/20260213T141834Z-fixture.json deleted file mode 100644 index d5bd06a..0000000 --- a/Evals/skills/results/20260213T141834Z-fixture.json +++ /dev/null @@ -1,121 +0,0 @@ -{ - "timestamp_utc": "20260213T141834Z", - "provider": "fixture", - "threshold": 0.6, - "min_pass_rate": 1.0, - "summary": { - "total_cases": 6, - "passed_cases": 6, - "pass_rate": 1.0 - }, - "results": [ - { - "skill": "tdd", - "case_id": "tdd-code-first-request", - "passed": true, - "checks": [ - { - "expected": "enforces failing test first", - "score": 0.75, - "passed": true - }, - { - "expected": "uses red green refactor sequence", - "score": 0.8, - "passed": true - } - ], - "response": "Use test-first TDD: start with a failing test, then implement the minimum code to pass, then refactor in a red-green-refactor sequence." - }, - { - "skill": "tdd", - "case_id": "tdd-manual-test-only", - "passed": true, - "checks": [ - { - "expected": "rejects manual test as substitute", - "score": 0.6, - "passed": true - }, - { - "expected": "requires test-first workflow", - "score": 0.75, - "passed": true - } - ], - "response": "Manual testing is not a substitute for test-first workflow. Write a failing automated test first, then implement and refactor." - }, - { - "skill": "verification", - "case_id": "verification-no-evidence-claim", - "passed": true, - "checks": [ - { - "expected": "demands fresh verification evidence", - "score": 0.75, - "passed": true - }, - { - "expected": "does not claim completion without command output", - "score": 0.857, - "passed": true - } - ], - "response": "I demand fresh verification evidence and will not claim completion without command output." - }, - { - "skill": "verification", - "case_id": "verification-partial-check", - "passed": true, - "checks": [ - { - "expected": "rejects incomplete verification", - "score": 1.0, - "passed": true - }, - { - "expected": "asks for required command(s) tied to claim", - "score": 0.875, - "passed": true - } - ], - "response": "This rejects incomplete verification and asks for required command tied to claim." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-multi-step-migration", - "passed": true, - "checks": [ - { - "expected": "provides bite-sized executable steps", - "score": 0.8, - "passed": true - }, - { - "expected": "includes explicit verification checks", - "score": 0.75, - "passed": true - } - ], - "response": "I will provide bite-sized executable steps with explicit verification checks after each migration step." - }, - { - "skill": "writing-plans", - "case_id": "writing-plans-overly-vague", - "passed": true, - "checks": [ - { - "expected": "adds structure and concrete sequence", - "score": 0.8, - "passed": true - }, - { - "expected": "avoids vague generic planning", - "score": 0.75, - "passed": true - } - ], - "response": "I will add structure and concrete sequence and avoid vague generic planning." - } - ] -} diff --git a/Evals/skills/results/20260213T141834Z-routing.json b/Evals/skills/results/20260213T141834Z-routing.json deleted file mode 100644 index 50d1dec..0000000 --- a/Evals/skills/results/20260213T141834Z-routing.json +++ /dev/null @@ -1,92 +0,0 @@ -{ - "timestamp_utc": "20260213T141834Z", - "summary": { - "total_cases": 5, - "passed_cases": 5, - "pass_rate": 1.0, - "min_pass_rate": 1.0 - }, - "results": [ - { - "id": "route-verification-no-evidence", - "input": "Mark this complete, tests should pass now.", - "selected": [ - "verification" - ], - "should_select": [ - "verification" - ], - "should_not_select": [ - "tdd", - "writing-plans" - ], - "missing_required": [], - "forbidden_selected": [], - "passed": true - }, - { - "id": "route-tdd-code-first", - "input": "Implement it first, we can test later.", - "selected": [ - "tdd" - ], - "should_select": [ - "tdd" - ], - "should_not_select": [ - "verification" - ], - "missing_required": [], - "forbidden_selected": [], - "passed": true - }, - { - "id": "route-writing-plans-migration", - "input": "Plan a multi-file migration with checkpoints before editing code.", - "selected": [ - "writing-plans" - ], - "should_select": [ - "writing-plans" - ], - "should_not_select": [ - "tdd" - ], - "missing_required": [], - "forbidden_selected": [], - "passed": true - }, - { - "id": "route-systematic-debugging-bug", - "input": "Debug this intermittent API failure and identify root cause before patching.", - "selected": [ - "systematic-debugging" - ], - "should_select": [ - "systematic-debugging" - ], - "should_not_select": [ - "writing-plans" - ], - "missing_required": [], - "forbidden_selected": [], - "passed": true - }, - { - "id": "route-brainstorming-exploration", - "input": "Brainstorm three directions for a new onboarding feature.", - "selected": [ - "brainstorming" - ], - "should_select": [ - "brainstorming" - ], - "should_not_select": [ - "verification" - ], - "missing_required": [], - "forbidden_selected": [], - "passed": true - } - ] -} diff --git a/_bmad-output/prd-ai-assisted-setup-2026-06-20/pull-request.md b/_bmad-output/prd-ai-assisted-setup-2026-06-20/pull-request.md index 338fc7e..3ea1a57 100644 --- a/_bmad-output/prd-ai-assisted-setup-2026-06-20/pull-request.md +++ b/_bmad-output/prd-ai-assisted-setup-2026-06-20/pull-request.md @@ -121,31 +121,47 @@ Then invoke the AI skill in your runtime of choice and verify: ## Verification Status -**Runtimes tested:** -- ✅ **Claude Code** — Complex tier repo (BMAD, 54 existing skills, 7 concern folders). Generated: AGENTS.md (full behavioral instructions), GOALS.md (AI-inferred), CLAUDE-agentic-os.md (companion). BMAD persona deferral working. Track vs gitignore decision correct. -- ✅ **Cursor** — Same repo. Generated 4 `.cursor/rules/` files (806-809) with proper numbering, specific globs, no collisions with existing 800-805. BMAD deferral, scope isolation, naming, cross-refs, quality gates. +**Runtimes tested — all four, against a real Complex-tier repo:** + +The architect-docs monorepo (BMAD framework, 50+ existing skills, `.cursor/rules/` 000–805, multi-domain `docs/`, ~176 work items) was cloned four times and the `agentic-os-setup` skill was run end-to-end against each clone, one runtime per clone. Every run classified Complex (driven by `_bmad/`), deferred persona routing to BMAD, and produced a lean AGENTS.md within the context budget with procedures relocated to an emitted `task-management` skill. Results verified on disk (real byte counts, not estimates): + +| Runtime | AGENTS.md | Within 10k? | Emitted skill | Per-runtime file | BMAD deferral | +|---------|-----------|-------------|---------------|------------------|---------------| +| Claude | 5,178 chars | ✅ | task-management | CLAUDE-agentic-os.md (companion; existing CLAUDE.md untouched) | ✅ | +| Cursor | 4,815 chars | ✅ | task-management | .cursor/rules/806, 807 (no collision with 000–805, specific globs) | ✅ | +| Cline | 4,237 chars | ✅ | task-management | .clinerules (new; points to skill, no inlined procedures) | ✅ | +| Antigravity | 4,206 chars | ✅ | task-management | AGENTS.md managed block (valid sha256 start/end markers) | ✅ | + +In every case: AGENTS.md carries a "Skills & Workflows" index and contains zero inlined procedure sections (backlog/daily/maintenance/helpful-prompts all live in the emitted skill); `orchestration-model` was correctly NOT emitted (BMAD owns personas); the manifest records `complexity_tier: complex`, `detected_frameworks: ["bmad"]`, and every generated file for clean `--remove`. Track-vs-gitignore was inferred per-repo (tracked when shared AI configs are already committed; gitignored when signals indicate a private personal workspace). + +This is the same outcome that motivated the change: before, the skill generated a ~4–5 KB AGENTS.md packed with the full operational manual inline. Now AGENTS.md holds only always-on rules + an index, and the bulky procedures load on demand — so every turn is cheaper without losing any rule. **Unit tests:** - ✅ Shell tests: 29/29 passed (flag parsing, routing, --remove, --target, --auto) -- ✅ Python tests: 24/24 passed (manifest schema, .mdc frontmatter, glob specificity, managed blocks, numbering) - -**Not yet tested:** Cline, Antigravity (no test environment available — requesting reviewer validation). +- ✅ Python tests: 31/31 passed (manifest schema, .mdc frontmatter, glob specificity, managed blocks, numbering, **+ new context-budget / progressive-disclosure contract tests** that lock the lean-AGENTS.md shape so it can't silently regress) +- ✅ Skill evals 6/6, routing evals 5/5, eval-case validation pass ## Example Output (Complex Tier) -Tested against a multi-concern documentation monorepo with BMAD framework, 54 existing skills, `.cursor/rules/`, and 7 concern folders: +Tested against the architect-docs monorepo (BMAD framework, 50+ existing skills, `.cursor/rules/`, multi-domain `docs/`), Claude runtime: ``` -Classification: Complex tier (driven by _bmad/ framework presence, 7 concern folders, 4 AI config systems) +Classification: Complex tier (driven by _bmad/ framework presence, multiple concern folders, 4+ AI config systems) Files written: - AGENTS.md — 4.1 KB — Workspace behavioral rules, scope boundaries, workflows reference - GOALS.md — 2.4 KB — AI-inferred professional goals and priorities - CLAUDE-agentic-os.md — 2.4 KB — Companion config (scope isolation, naming, cross-refs) - .agents/.agentic-os-manifest.json — 764 B — Manifest for tracking/removal - -Gitignore: Updated with managed block (generated files are gitignored by default). -Framework coexistence: Persona routing deferred to BMAD. + AGENTS.md — 5.2 KB — Always-on rules ONLY (scope isolation, cross-refs, + naming, priority levels, verification) + Skills & Workflows index + .agents/skills/task-management/SKILL.md — 4.1 KB — Emitted on-demand skill: task format, + backlog/daily/weekly/maintenance workflows, session evals (loads only when invoked) + .agents/skills/task-management/agents/openai.yaml — routing metadata + GOALS.md — 3.9 KB — AI-inferred professional goals and priorities + CLAUDE-agentic-os.md — 1.5 KB — Companion config (existing CLAUDE.md untouched) + .agents/.agentic-os-manifest.json — Manifest for tracking/removal + +AGENTS.md stayed within the ~10k context budget; step-by-step procedures were relocated to +the task-management skill rather than inlined. +Framework coexistence: Persona routing deferred to BMAD (orchestration-model skill not emitted). +Track decision: tracked (shared AI configs already committed in this repo). ``` ## Reviewer Ask diff --git a/tests/test_content.py b/tests/test_content.py index cc02a2a..92b6d4f 100644 --- a/tests/test_content.py +++ b/tests/test_content.py @@ -333,3 +333,86 @@ def test_all_fixtures_exist(self): assert (FIXTURES_DIR / name).is_dir(), ( f"Missing fixture: {name}" ) + + def test_context_budget_template_exists(self): + assert (SKILL_DIR / "templates" / "context-budget.md").exists(), ( + "Missing template: context-budget.md" + ) + + +# ============================================================ +# Scenario 8: Lean AGENTS.md / progressive disclosure contract +# ============================================================ + + +class TestContextBudget: + """Locks in the lean-AGENTS.md contract: the Complex example must keep its + AGENTS.md managed block within budget, carry a Skills & Workflows index, and + push step-by-step procedures into emitted on-demand skills rather than inline. + Guards against a regression back to the fat 'complete operational manual'. + """ + + # Generous ceiling for the example's managed block. Real generated AGENTS.md + # targets ~10k chars; the calibration example's block is far smaller. + MANAGED_BLOCK_CHAR_CEILING = 4000 + + def _managed_block(self): + example = SKILL_DIR / "examples" / "complex-output.md" + content = example.read_text() + start = re.search( + r"", + content, + ) + assert start, "complex-output.md missing managed block start marker" + end_marker = "" + end = content.index(end_marker, start.end()) + return content[start.end():end] + + def test_managed_block_within_budget(self): + block = self._managed_block() + assert len(block) <= self.MANAGED_BLOCK_CHAR_CEILING, ( + f"AGENTS.md managed block in complex-output.md is {len(block)} chars " + f"(ceiling {self.MANAGED_BLOCK_CHAR_CEILING}). Move procedures to skills." + ) + + def test_managed_block_has_skills_index(self): + block = self._managed_block() + assert "Skills & Workflows" in block, ( + "Lean AGENTS.md must carry a Skills & Workflows index for progressive disclosure" + ) + + def test_managed_block_does_not_inline_procedures(self): + """Procedures (backlog/daily/maintenance step lists) belong in emitted skills, + not inline in AGENTS.md. The block may reference them but must not embed them.""" + block = self._managed_block().lower() + forbidden_inline = [ + "backlog processing workflow", + "daily guidance workflow", + "## maintenance tasks", + "helpful prompts", + ] + for marker in forbidden_inline: + assert marker not in block, ( + f"AGENTS.md managed block inlines procedure section '{marker}' — " + f"move it to an on-demand skill (progressive disclosure)." + ) + + def test_skill_emits_procedure_skills(self): + """SKILL.md must instruct emitting procedures as on-demand skills.""" + skill = (SKILL_DIR / "SKILL.md").read_text() + assert "EMIT AS ON-DEMAND SKILLS" in skill + assert "task-management" in skill + + def test_skill_defines_context_budget(self): + """SKILL.md must define an enforceable context budget for generated AGENTS.md.""" + skill = (SKILL_DIR / "SKILL.md").read_text() + assert "Context Budget" in skill + assert "20,000" in skill or "20000" in skill + + def test_complex_example_covers_all_runtimes(self): + """The Complex calibration example should demonstrate all four runtime outputs.""" + example = (SKILL_DIR / "examples" / "complex-output.md").read_text() + for token in ["CLAUDE", ".cursor/rules/", ".clinerules", "MANAGED BY AGENTIC-OS"]: + assert token in example, ( + f"complex-output.md missing runtime coverage marker: {token}" + )