From 1da353aca61535a8a51a10d8ed5f68e964100c13 Mon Sep 17 00:00:00 2001 From: Vibe Nuage Agent Date: Thu, 3 Sep 2026 11:23:56 +0000 Subject: [PATCH 01/11] feat(cli): add Mistral Vibe support Replay of the feature work from vibe/mistral-support-3eed3a: f430866c, 96f9175a, 6424d956, b63d864e, aa55ce44, e5d03979, 3e23f9b3, replayed onto next. --- .aidd/config.json | 5 + aidd-context/.mistral-plugin/plugin.json | 36 ++ aidd-context/hooks/hooks.json | 14 + aidd-context/hooks/update_memory.js | 325 +++++++++++++++ aidd-context/skills/00-onboard/SKILL.md | 32 ++ .../skills/00-onboard/actions/01-scan.md | 27 ++ .../skills/00-onboard/actions/02-assess.md | 25 ++ .../skills/00-onboard/actions/03-present.md | 40 ++ .../skills/00-onboard/actions/04-run.md | 33 ++ .../skills/00-onboard/assets/banner.txt | 7 + .../skills/00-onboard/assets/report.md | 66 +++ .../skills/00-onboard/references/flow.md | 27 ++ .../00-onboard/references/order/idle-menu.md | 14 + .../00-onboard/references/order/ranking.md | 10 + .../00-onboard/references/order/screen-map.md | 9 + .../00-onboard/references/run/replies.md | 14 + .../00-onboard/references/run/return.md | 3 + .../skills/00-onboard/references/run/tiers.md | 13 + .../00-onboard/references/state/detection.md | 18 + .../00-onboard/references/state/done-rule.md | 6 + .../00-onboard/references/state/hedge.md | 12 + .../00-onboard/references/state/zones.md | 41 ++ aidd-context/skills/01-bootstrap/SKILL.md | 39 ++ .../01-bootstrap/actions/01-gather-needs.md | 26 ++ .../actions/02-propose-candidates.md | 26 ++ .../actions/03-audit-candidates.md | 38 ++ .../actions/04-pick-and-design.md | 26 ++ .../actions/05-write-install-md.md | 31 ++ .../skills/01-bootstrap/assets/checklist.md | 39 ++ .../01-bootstrap/assets/install-template.md | 63 +++ .../references/stack-heuristics.md | 75 ++++ .../skills/02-project-memory/SKILL.md | 33 ++ .../02-project-memory/actions/01-scan.md | 30 ++ .../02-project-memory/actions/02-write.md | 30 ++ .../02-project-memory/actions/03-check.md | 38 ++ .../02-project-memory/actions/04-sync.md | 34 ++ .../skills/02-project-memory/assets/report.md | 56 +++ .../02-project-memory/assets/scan-summary.md | 23 ++ .../assets/templates/AGENTS.md | 45 ++ .../assets/templates/CONTRIBUTING.md | 21 + .../assets/templates/GUIDELINES.md | 20 + .../assets/templates/README.md | 17 + .../assets/templates/memory/README.md | 33 ++ .../assets/templates/memory/api/api.md | 22 + .../templates/memory/api/integration.md | 17 + .../assets/templates/memory/auth/auth.md | 26 ++ .../templates/memory/backlog/backlog.md | 50 +++ .../assets/templates/memory/cli/cli.md | 20 + .../templates/memory/core/architecture.md | 32 ++ .../templates/memory/core/codebase-map.md | 27 ++ .../memory/core/coding-assertions.md | 29 ++ .../templates/memory/core/project-brief.md | 29 ++ .../assets/templates/memory/core/testing.md | 31 ++ .../assets/templates/memory/core/vcs.md | 29 ++ .../assets/templates/memory/data/data.md | 29 ++ .../templates/memory/database/database.md | 27 ++ .../templates/memory/deployment/deployment.md | 31 ++ .../templates/memory/desktop/desktop.md | 20 + .../templates/memory/ecosystem/ecosystem.md | 32 ++ .../assets/templates/memory/infra/infra.md | 25 ++ .../templates/memory/messaging/messaging.md | 25 ++ .../assets/templates/memory/mobile/mobile.md | 33 ++ .../templates/memory/package/package.md | 21 + .../templates/memory/realtime/realtime.md | 25 ++ .../assets/templates/memory/ui/design.md | 25 ++ .../assets/templates/memory/ui/forms.md | 17 + .../assets/templates/memory/ui/navigation.md | 22 + .../references/capability-signals.md | 24 ++ .../references/ecosystem-signals.md | 47 +++ .../references/memory-destinations.md | 36 ++ .../references/memory-rules.md | 13 + .../references/reading-sources.md | 45 ++ .../references/review-protocol.md | 16 + .../02-project-memory/references/structure.md | 20 + .../02-project-memory/references/tools.md | 17 + .../skills/03-context-generate/SKILL.md | 21 + .../skills/04-skill-generate/SKILL.md | 31 ++ .../04-skill-generate/actions/01-scope.md | 28 ++ .../04-skill-generate/actions/02-plan.md | 27 ++ .../04-skill-generate/actions/03-write.md | 34 ++ .../04-skill-generate/actions/04-validate.md | 25 ++ .../assets/action-template.md | 24 ++ .../assets/skill-template.md | 28 ++ .../04-skill-generate/references/naming.md | 18 + .../references/review-protocol.md | 7 + .../references/scope-frame.md | 24 ++ .../references/skill-authoring.md | 40 ++ .../references/skill-tree.md | 16 + .../references/tool-detect.md | 13 + .../references/tool-write.md | 25 ++ aidd-context/skills/05-rule-generate/SKILL.md | 29 ++ .../actions/01-capture-rule.md | 28 ++ .../05-rule-generate/actions/02-write-rule.md | 26 ++ .../05-rule-generate/actions/03-validate.md | 22 + .../05-rule-generate/assets/rule-template.md | 12 + .../references/rule-authoring.md | 37 ++ .../05-rule-generate/references/tool-paths.md | 53 +++ .../skills/06-agent-generate/SKILL.md | 29 ++ .../actions/01-capture-agent.md | 27 ++ .../actions/02-write-agent.md | 26 ++ .../06-agent-generate/actions/03-validate.md | 21 + .../assets/agent-template.md | 22 + .../references/agent-authoring.md | 28 ++ .../references/tool-paths.md | 58 +++ .../skills/07-command-generate/SKILL.md | 29 ++ .../actions/01-capture-command.md | 27 ++ .../actions/02-write-command.md | 26 ++ .../actions/03-validate.md | 21 + .../assets/command-template.md | 14 + .../references/command-authoring.md | 45 ++ .../references/tool-paths.md | 49 +++ aidd-context/skills/08-hook-generate/SKILL.md | 30 ++ .../actions/01-capture-hook.md | 37 ++ .../08-hook-generate/actions/02-write-hook.md | 25 ++ .../08-hook-generate/actions/03-validate.md | 23 ++ .../assets/hook-script-template.sh | 15 + .../assets/hook-template.json | 10 + .../references/hook-authoring.md | 47 +++ .../08-hook-generate/references/tool-paths.md | 84 ++++ aidd-context/skills/09-mermaid/SKILL.md | 29 ++ .../skills/09-mermaid/actions/01-mermaid.md | 24 ++ .../references/mermaid-conventions.md | 46 +++ aidd-context/skills/10-learn/SKILL.md | 35 ++ .../skills/10-learn/actions/01-source.md | 26 ++ .../skills/10-learn/actions/02-gather.md | 25 ++ .../skills/10-learn/actions/03-assess.md | 29 ++ .../skills/10-learn/actions/04-write.md | 29 ++ .../skills/10-learn/actions/05-sync.md | 28 ++ .../skills/10-learn/assets/adr-template.md | 24 ++ .../skills/10-learn/assets/learning-packet.md | 13 + .../10-learn/assets/recommendation-table.md | 5 + .../skills/10-learn/assets/write-report.md | 7 + .../skills/10-learn/references/assessment.md | 25 ++ .../10-learn/references/destinations.md | 27 ++ .../10-learn/references/gather-protocol.md | 34 ++ .../10-learn/references/review-protocol.md | 13 + .../skills/10-learn/references/sources.md | 28 ++ .../10-learn/references/sync-arguments.md | 17 + aidd-context/skills/11-explore/SKILL.md | 39 ++ .../skills/11-explore/actions/01-survey.md | 24 ++ .../skills/11-explore/actions/02-drill.md | 26 ++ .../11-explore/references/ai-mapping.md | 59 +++ .../skills/11-explore/scripts/list-rules.mjs | 198 +++++++++ aidd-context/skills/12-cook/SKILL.md | 31 ++ .../skills/12-cook/actions/01-list.md | 28 ++ .../skills/12-cook/actions/02-upsert.md | 30 ++ .../skills/12-cook/actions/03-research.md | 32 ++ .../skills/12-cook/actions/04-apply.md | 25 ++ .../skills/12-cook/assets/recipe-template.md | 50 +++ .../assets/recipes/install-aiddy-in-codex.md | 54 +++ .../assets/recipes/mcp-installation.md | 60 +++ .../12-cook/assets/recipes/ship-a-feature.md | 79 ++++ .../12-cook/assets/recipes/start-a-project.md | 69 ++++ .../assets/recipes/token-optimization.md | 277 +++++++++++++ .../12-cook/assets/research-checklist.md | 9 + .../12-cook/assets/research-goal-checklist.md | 12 + .../12-cook/references/recipe-contract.md | 32 ++ .../12-cook/references/recipe-locations.md | 27 ++ .../12-cook/references/research-playbook.md | 38 ++ .../skills/tools/references/build-contract.md | 4 +- cli/aidd_docs/memory/codebase-map.md | 1 + cli/assets/configs/mistral/settings.json | 1 + .../contexts/tools/domain/build-contract.ts | 2 +- .../tools/domain/profiles/mistral/build.ts | 123 ++++++ .../domain/profiles/mistral/mistral-paths.ts | 31 ++ .../mistral/mistral-skill-frontmatter.ts | 19 + .../tools/domain/profiles/mistral/profile.ts | 132 ++++++ .../strategies/flat-build-strategy.ts | 21 +- cli/src/kernel/tool.ts | 3 +- cli/src/presentation/commands/translate.ts | 2 +- cli/src/presentation/prompts/menu-use-case.ts | 4 +- cli/src/runtime/assets/asset-loader.ts | 2 + cli/src/runtime/wiring/tools.ts | 1 + cli/tests/architecture/comments.arch.test.ts | 2 +- .../tool-addition-cost.arch.test.ts | 8 +- .../clean-native-cache.integration.test.ts | 1 + .../marketplace-remove-use-case.unit.test.ts | 1 + ...encode-materialization.integration.test.ts | 1 + .../contexts/framework/application/helpers.ts | 1 + .../application/init-use-case.unit.test.ts | 1 + ...list-installed-rules-use-case.unit.test.ts | 1 + .../plugin-remove-use-case.unit.test.ts | 1 + .../shared/remove-project-hooks.unit.test.ts | 1 + .../application/status-use-case.unit.test.ts | 1 + .../uninstall-use-case.unit.test.ts | 3 +- .../domain/install-scope.unit.test.ts | 1 + .../plugin-asset-translation.unit.test.ts | 1 + .../framework/domain/setup-flow.unit.test.ts | 1 + ...ibution-reader-adapter.integration.test.ts | 1 + .../diagnose-telemetry-use-case.unit.test.ts | 5 + .../read-local-cost-sweep.unit.test.ts | 13 + .../read-local-cost-use-case.unit.test.ts | 1 + .../report-cost-use-case.unit.test.ts | 12 + .../application/tool-attribution.unit.test.ts | 1 + .../domain/cost-report-envelope.unit.test.ts | 1 + .../domain/metrics-contract.unit.test.ts | 1 + ...metry-evidence-adapter.integration.test.ts | 1 + ...plugin-root-token-declaration.unit.test.ts | 1 + .../mistral-skill-frontmatter.unit.test.ts | 22 + .../domain/profiles/mistral.unit.test.ts | 31 ++ .../domain/registry-conformance.unit.test.ts | 3 + .../telemetry-route-supply.unit.test.ts | 1 + .../tools/domain/tool-config.unit.test.ts | 4 +- ...egistry-reader-adapter.integration.test.ts | 1 + .../flat-build-strategy.integration.test.ts | 169 +++++++- ...lugin-content-translator-skip.unit.test.ts | 16 + cli/tests/e2e/framework-build.e2e.test.ts | 23 ++ cli/tests/e2e/persona.e2e.test.ts | 94 +++-- .../cli-owns-read/expected-envelope.json | 14 + .../golden/framework-build-golden.e2e.test.ts | 12 +- cli/tests/golden/golden-baseline.e2e.test.ts | 2 +- .../snapshots/framework-build/golden.json | 388 ++++++++++++++++++ cli/tests/golden/snapshots/help/surface.json | 2 +- .../golden/snapshots/phase0/snapshot.json | 2 +- cli/tests/helpers/ports/build-unit-deps.ts | 1 + cli/tests/kernel/markdown.unit.test.ts | 12 + cli/tests/kernel/tool.unit.test.ts | 1 + .../commands/setup-wiring.integration.test.ts | 1 + .../translate-wiring.integration.test.ts | 3 +- .../display/cost-report-display.unit.test.ts | 1 + .../display/telemetry-display.unit.test.ts | 1 + .../interactive-menu-use-case.unit.test.ts | 4 +- .../references/tool-detect.md | 1 + .../references/tool-write.md | 2 + .../hooks/lib/plugin-version.cjs | 1 + 225 files changed, 6452 insertions(+), 74 deletions(-) create mode 100644 .aidd/config.json create mode 100644 aidd-context/.mistral-plugin/plugin.json create mode 100644 aidd-context/hooks/hooks.json create mode 100644 aidd-context/hooks/update_memory.js create mode 100644 aidd-context/skills/00-onboard/SKILL.md create mode 100644 aidd-context/skills/00-onboard/actions/01-scan.md create mode 100644 aidd-context/skills/00-onboard/actions/02-assess.md create mode 100644 aidd-context/skills/00-onboard/actions/03-present.md create mode 100644 aidd-context/skills/00-onboard/actions/04-run.md create mode 100644 aidd-context/skills/00-onboard/assets/banner.txt create mode 100644 aidd-context/skills/00-onboard/assets/report.md create mode 100644 aidd-context/skills/00-onboard/references/flow.md create mode 100644 aidd-context/skills/00-onboard/references/order/idle-menu.md create mode 100644 aidd-context/skills/00-onboard/references/order/ranking.md create mode 100644 aidd-context/skills/00-onboard/references/order/screen-map.md create mode 100644 aidd-context/skills/00-onboard/references/run/replies.md create mode 100644 aidd-context/skills/00-onboard/references/run/return.md create mode 100644 aidd-context/skills/00-onboard/references/run/tiers.md create mode 100644 aidd-context/skills/00-onboard/references/state/detection.md create mode 100644 aidd-context/skills/00-onboard/references/state/done-rule.md create mode 100644 aidd-context/skills/00-onboard/references/state/hedge.md create mode 100644 aidd-context/skills/00-onboard/references/state/zones.md create mode 100644 aidd-context/skills/01-bootstrap/SKILL.md create mode 100644 aidd-context/skills/01-bootstrap/actions/01-gather-needs.md create mode 100644 aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md create mode 100644 aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md create mode 100644 aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md create mode 100644 aidd-context/skills/01-bootstrap/actions/05-write-install-md.md create mode 100644 aidd-context/skills/01-bootstrap/assets/checklist.md create mode 100644 aidd-context/skills/01-bootstrap/assets/install-template.md create mode 100644 aidd-context/skills/01-bootstrap/references/stack-heuristics.md create mode 100644 aidd-context/skills/02-project-memory/SKILL.md create mode 100644 aidd-context/skills/02-project-memory/actions/01-scan.md create mode 100644 aidd-context/skills/02-project-memory/actions/02-write.md create mode 100644 aidd-context/skills/02-project-memory/actions/03-check.md create mode 100644 aidd-context/skills/02-project-memory/actions/04-sync.md create mode 100644 aidd-context/skills/02-project-memory/assets/report.md create mode 100644 aidd-context/skills/02-project-memory/assets/scan-summary.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/AGENTS.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/CONTRIBUTING.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/GUIDELINES.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/README.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/README.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/auth/auth.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/cli/cli.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/core/codebase-map.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/core/coding-assertions.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/core/project-brief.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/data/data.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/desktop/desktop.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/infra/infra.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/messaging/messaging.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/mobile/mobile.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/package/package.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/realtime/realtime.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/ui/forms.md create mode 100644 aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md create mode 100644 aidd-context/skills/02-project-memory/references/capability-signals.md create mode 100644 aidd-context/skills/02-project-memory/references/ecosystem-signals.md create mode 100644 aidd-context/skills/02-project-memory/references/memory-destinations.md create mode 100644 aidd-context/skills/02-project-memory/references/memory-rules.md create mode 100644 aidd-context/skills/02-project-memory/references/reading-sources.md create mode 100644 aidd-context/skills/02-project-memory/references/review-protocol.md create mode 100644 aidd-context/skills/02-project-memory/references/structure.md create mode 100644 aidd-context/skills/02-project-memory/references/tools.md create mode 100644 aidd-context/skills/03-context-generate/SKILL.md create mode 100644 aidd-context/skills/04-skill-generate/SKILL.md create mode 100644 aidd-context/skills/04-skill-generate/actions/01-scope.md create mode 100644 aidd-context/skills/04-skill-generate/actions/02-plan.md create mode 100644 aidd-context/skills/04-skill-generate/actions/03-write.md create mode 100644 aidd-context/skills/04-skill-generate/actions/04-validate.md create mode 100644 aidd-context/skills/04-skill-generate/assets/action-template.md create mode 100644 aidd-context/skills/04-skill-generate/assets/skill-template.md create mode 100644 aidd-context/skills/04-skill-generate/references/naming.md create mode 100644 aidd-context/skills/04-skill-generate/references/review-protocol.md create mode 100644 aidd-context/skills/04-skill-generate/references/scope-frame.md create mode 100644 aidd-context/skills/04-skill-generate/references/skill-authoring.md create mode 100644 aidd-context/skills/04-skill-generate/references/skill-tree.md create mode 100644 aidd-context/skills/04-skill-generate/references/tool-detect.md create mode 100644 aidd-context/skills/04-skill-generate/references/tool-write.md create mode 100644 aidd-context/skills/05-rule-generate/SKILL.md create mode 100644 aidd-context/skills/05-rule-generate/actions/01-capture-rule.md create mode 100644 aidd-context/skills/05-rule-generate/actions/02-write-rule.md create mode 100644 aidd-context/skills/05-rule-generate/actions/03-validate.md create mode 100644 aidd-context/skills/05-rule-generate/assets/rule-template.md create mode 100644 aidd-context/skills/05-rule-generate/references/rule-authoring.md create mode 100644 aidd-context/skills/05-rule-generate/references/tool-paths.md create mode 100644 aidd-context/skills/06-agent-generate/SKILL.md create mode 100644 aidd-context/skills/06-agent-generate/actions/01-capture-agent.md create mode 100644 aidd-context/skills/06-agent-generate/actions/02-write-agent.md create mode 100644 aidd-context/skills/06-agent-generate/actions/03-validate.md create mode 100644 aidd-context/skills/06-agent-generate/assets/agent-template.md create mode 100644 aidd-context/skills/06-agent-generate/references/agent-authoring.md create mode 100644 aidd-context/skills/06-agent-generate/references/tool-paths.md create mode 100644 aidd-context/skills/07-command-generate/SKILL.md create mode 100644 aidd-context/skills/07-command-generate/actions/01-capture-command.md create mode 100644 aidd-context/skills/07-command-generate/actions/02-write-command.md create mode 100644 aidd-context/skills/07-command-generate/actions/03-validate.md create mode 100644 aidd-context/skills/07-command-generate/assets/command-template.md create mode 100644 aidd-context/skills/07-command-generate/references/command-authoring.md create mode 100644 aidd-context/skills/07-command-generate/references/tool-paths.md create mode 100644 aidd-context/skills/08-hook-generate/SKILL.md create mode 100644 aidd-context/skills/08-hook-generate/actions/01-capture-hook.md create mode 100644 aidd-context/skills/08-hook-generate/actions/02-write-hook.md create mode 100644 aidd-context/skills/08-hook-generate/actions/03-validate.md create mode 100644 aidd-context/skills/08-hook-generate/assets/hook-script-template.sh create mode 100644 aidd-context/skills/08-hook-generate/assets/hook-template.json create mode 100644 aidd-context/skills/08-hook-generate/references/hook-authoring.md create mode 100644 aidd-context/skills/08-hook-generate/references/tool-paths.md create mode 100644 aidd-context/skills/09-mermaid/SKILL.md create mode 100644 aidd-context/skills/09-mermaid/actions/01-mermaid.md create mode 100644 aidd-context/skills/09-mermaid/references/mermaid-conventions.md create mode 100644 aidd-context/skills/10-learn/SKILL.md create mode 100644 aidd-context/skills/10-learn/actions/01-source.md create mode 100644 aidd-context/skills/10-learn/actions/02-gather.md create mode 100644 aidd-context/skills/10-learn/actions/03-assess.md create mode 100644 aidd-context/skills/10-learn/actions/04-write.md create mode 100644 aidd-context/skills/10-learn/actions/05-sync.md create mode 100644 aidd-context/skills/10-learn/assets/adr-template.md create mode 100644 aidd-context/skills/10-learn/assets/learning-packet.md create mode 100644 aidd-context/skills/10-learn/assets/recommendation-table.md create mode 100644 aidd-context/skills/10-learn/assets/write-report.md create mode 100644 aidd-context/skills/10-learn/references/assessment.md create mode 100644 aidd-context/skills/10-learn/references/destinations.md create mode 100644 aidd-context/skills/10-learn/references/gather-protocol.md create mode 100644 aidd-context/skills/10-learn/references/review-protocol.md create mode 100644 aidd-context/skills/10-learn/references/sources.md create mode 100644 aidd-context/skills/10-learn/references/sync-arguments.md create mode 100644 aidd-context/skills/11-explore/SKILL.md create mode 100644 aidd-context/skills/11-explore/actions/01-survey.md create mode 100644 aidd-context/skills/11-explore/actions/02-drill.md create mode 100644 aidd-context/skills/11-explore/references/ai-mapping.md create mode 100644 aidd-context/skills/11-explore/scripts/list-rules.mjs create mode 100644 aidd-context/skills/12-cook/SKILL.md create mode 100644 aidd-context/skills/12-cook/actions/01-list.md create mode 100644 aidd-context/skills/12-cook/actions/02-upsert.md create mode 100644 aidd-context/skills/12-cook/actions/03-research.md create mode 100644 aidd-context/skills/12-cook/actions/04-apply.md create mode 100644 aidd-context/skills/12-cook/assets/recipe-template.md create mode 100644 aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md create mode 100644 aidd-context/skills/12-cook/assets/recipes/mcp-installation.md create mode 100644 aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md create mode 100644 aidd-context/skills/12-cook/assets/recipes/start-a-project.md create mode 100644 aidd-context/skills/12-cook/assets/recipes/token-optimization.md create mode 100644 aidd-context/skills/12-cook/assets/research-checklist.md create mode 100644 aidd-context/skills/12-cook/assets/research-goal-checklist.md create mode 100644 aidd-context/skills/12-cook/references/recipe-contract.md create mode 100644 aidd-context/skills/12-cook/references/recipe-locations.md create mode 100644 aidd-context/skills/12-cook/references/research-playbook.md create mode 100644 cli/assets/configs/mistral/settings.json create mode 100644 cli/src/contexts/tools/domain/profiles/mistral/build.ts create mode 100644 cli/src/contexts/tools/domain/profiles/mistral/mistral-paths.ts create mode 100644 cli/src/contexts/tools/domain/profiles/mistral/mistral-skill-frontmatter.ts create mode 100644 cli/src/contexts/tools/domain/profiles/mistral/profile.ts create mode 100644 cli/tests/contexts/tools/domain/profiles/mistral-skill-frontmatter.unit.test.ts create mode 100644 cli/tests/contexts/tools/domain/profiles/mistral.unit.test.ts diff --git a/.aidd/config.json b/.aidd/config.json new file mode 100644 index 000000000..08eb95875 --- /dev/null +++ b/.aidd/config.json @@ -0,0 +1,5 @@ +{ + "telemetry": { + "enabled": false + } +} diff --git a/aidd-context/.mistral-plugin/plugin.json b/aidd-context/.mistral-plugin/plugin.json new file mode 100644 index 000000000..42b5d7803 --- /dev/null +++ b/aidd-context/.mistral-plugin/plugin.json @@ -0,0 +1,36 @@ +{ + "name": "aidd-context", + "description": "Knowledge production: project bootstrap, project init, generation of context artifacts (skills, agents, rules, commands, hooks), mermaid diagrams, learn, explore, recipe how-to sheets", + "version": "2.7.0", + "author": { + "name": "AI-Driven Dev", + "url": "https://github.com/ai-driven-dev" + }, + "homepage": "https://ai-driven.dev", + "repository": "https://github.com/ai-driven-dev/framework", + "license": "MIT", + "keywords": [ + "context", + "bootstrap", + "explore", + "skills", + "mermaid", + "onboard" + ], + "skills": [ + "./skills/00-onboard", + "./skills/01-bootstrap", + "./skills/02-project-memory", + "./skills/03-context-generate", + "./skills/04-skill-generate", + "./skills/05-rule-generate", + "./skills/06-agent-generate", + "./skills/07-command-generate", + "./skills/08-hook-generate", + "./skills/09-mermaid", + "./skills/10-learn", + "./skills/11-explore", + "./skills/12-cook" + ], + "hooks": "./hooks/hooks.json" +} diff --git a/aidd-context/hooks/hooks.json b/aidd-context/hooks/hooks.json new file mode 100644 index 000000000..4f1f9184a --- /dev/null +++ b/aidd-context/hooks/hooks.json @@ -0,0 +1,14 @@ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "node ${MISTRAL_PLUGIN_ROOT}/hooks/update_memory.js" + } + ] + } + ] + } +} diff --git a/aidd-context/hooks/update_memory.js b/aidd-context/hooks/update_memory.js new file mode 100644 index 000000000..191cde402 --- /dev/null +++ b/aidd-context/hooks/update_memory.js @@ -0,0 +1,325 @@ +#!/usr/bin/env node +/** + * update_memory.js - Syncs the project memory block in AI context files. + * + * Scans aidd_docs/memory/ and updates the block delimited by + * / in each + * context file with two tiers: + * - Root memory files -> always loaded, via a tool-appropriate reference. + * - internal/ and external/ -> listed (plain paths, no @), read on demand. + * + * Reference syntax for the always-loaded tier: + * CLAUDE.md / AGENTS.md -> @aidd_docs/memory/file.md + * .github/copilot-instructions -> [aidd_docs/memory/file.md](../aidd_docs/memory/file.md) + * + * Usage: + * node update_memory.js every context file already present + * node update_memory.js claude codex only those tools' context files + * + * The auto hook calls it with no argument. The project-memory skill passes the + * tools the user picked, so a context file the user did not choose is left + * alone even when it exists. + * + * It only ever fills a block that is already there. Creating the file, or the + * block inside it, is the skill's job. + */ + +// ── Constants ───────────────────────────────────────────────────── + +const DOCS_DIR = "aidd_docs"; +const MEMORY_SUBDIR = "memory"; +const ON_DEMAND_DIRS = ["internal", "external"]; +// HTML comment markers, not a bare tag. A line opening a +// bare tag starts an HTML block that runs to the next blank line, and an @import +// inside one is skipped by the context loader exactly like a fenced code block, +// so the memory silently never loads. A comment closes on its own line. +const BLOCK_OPEN = ""; +const BLOCK_CLOSE = ""; + +// The shape written before the markers above. Blocks already in a user's context +// file are rewritten to the new markers on the next run; without that they stop +// matching, the file is skipped with no output, and the memory stays unloaded. +const LEGACY_BLOCK_OPEN = ""; +const LEGACY_BLOCK_CLOSE = ""; +const ON_DEMAND_NOTE = ""; +const EXCLUDED_FILES = new Set([".gitkeep", "README.md"]); + +// Human-facing index of the memory bank. The hook refreshes the list between +// these markers; everything else in the file is hand-written and preserved. +const MEMORY_README = "README.md"; +const TOC_OPEN = ""; +const TOC_CLOSE = ""; + +const TARGET_FILES = [ + { path: "CLAUDE.md", syntax: "at" }, + { path: "AGENTS.md", syntax: "at" }, + { path: ".github/copilot-instructions.md", syntax: "link" }, +]; + +// Which context file each tool reads. Mirrors the skill's references/tools.md. +const TOOL_FILES = { + claude: "CLAUDE.md", + codex: "AGENTS.md", + cursor: "AGENTS.md", + opencode: "AGENTS.md", + copilot: ".github/copilot-instructions.md", +}; + +// ── Helpers ─────────────────────────────────────────────────────── + +function memoryPath(path, ...parts) { + return path.join(DOCS_DIR, MEMORY_SUBDIR, ...parts); +} + +// Read a file's text, or null if it does not exist. Opening directly (instead +// of an existsSync check first) avoids a time-of-check/time-of-use race: the +// file is touched exactly once. Real errors (permissions, etc.) still throw. +function readTextOrNull(fs, filePath) { + try { + return fs.readFileSync(filePath, "utf8"); + } catch (err) { + if (err.code === "ENOENT") return null; + throw err; + } +} + +// List a directory, or [] if it does not exist. Same single-touch rationale as +// readTextOrNull: no separate existence check before reading. +function readDirOrEmpty(fs, dir) { + try { + return fs.readdirSync(dir, { withFileTypes: true }); + } catch (err) { + if (err.code === "ENOENT") return []; + throw err; + } +} + +// Top-level .md at the root of memory/ (always-loaded tier). +function scanRootFiles(fs, path) { + return readDirOrEmpty(fs, memoryPath(path)) + .filter((e) => e.isFile() && e.name.endsWith(".md") && !EXCLUDED_FILES.has(e.name)) + .map((e) => memoryPath(path, e.name)) + .sort(); +} + +// .md under memory// recursively (on-demand tier). +function scanSubdir(fs, path, sub) { + const out = []; + const walk = (dir) => { + for (const e of readDirOrEmpty(fs, dir)) { + const full = path.join(dir, e.name); + if (e.isDirectory()) walk(full); + else if (e.name.endsWith(".md") && !EXCLUDED_FILES.has(e.name)) out.push(full); + } + }; + walk(memoryPath(path, sub)); + return out.sort(); +} + +function buildReference(syntax, filePath) { + const rel = filePath.replace(/\\/g, "/"); + return syntax === "link" ? `[${rel}](../${rel})` : `@${rel}`; +} + +function buildBlockContent(rootFiles, onDemandFiles, syntax) { + const lines = []; + for (const f of rootFiles) lines.push(buildReference(syntax, f)); + if (onDemandFiles.length > 0) { + lines.push("", ON_DEMAND_NOTE); + for (const f of onDemandFiles) lines.push(`- ${f.replace(/\\/g, "/")}`); + } + if (lines.length === 0) return "\n"; + // Blank line on each side of the content. The markers are comments, which + // close on their own line, but a context loader that treats any line opening + // with `<` as an HTML block running to the next blank line would otherwise + // swallow the imports. The blank lines hold under either reading. + return `\n\n${lines.join("\n")}\n\n`; +} + +// The real block is the one whose markers each own their line, outside any code +// fence. Substring search is not enough: these markers are the strings every +// upgrade note and migration doc quotes, and cutting on a quoted one would +// mangle that prose while leaving the real block untouched and unloaded. +function findBlockLines(lines, open, close) { + let fence = null; + let openLine = -1; + + for (let i = 0; i < lines.length; i++) { + const trimmed = lines[i].trim(); + const opener = /^(`{3,}|~{3,})/u.exec(trimmed); + + if (fence !== null) { + // A fence closes only on the same character, repeated at least as often, + // so a ``` inside a ```` example does not end it early. + if (opener && opener[1][0] === fence[0] && opener[1].length >= fence.length) fence = null; + continue; + } + if (opener) { + fence = opener[1]; + continue; + } + if (trimmed === open) openLine = i; + else if (trimmed === close && openLine !== -1) return { openLine, closeLine: i }; + } + + return null; +} + +// Replace the text between an open and close marker, leaving the rest intact. +function updateMarkers(content, open, close, innerContent) { + const lines = content.split("\n"); + const found = findBlockLines(lines, open, close); + if (found === null) return null; + + return ( + lines.slice(0, found.openLine + 1).join("\n") + + innerContent + + lines.slice(found.closeLine).join("\n") + ); +} + +// Rewrite a legacy block to the comment markers. +function migrateLegacyMarkers(content) { + const lines = content.split("\n"); + const found = findBlockLines(lines, LEGACY_BLOCK_OPEN, LEGACY_BLOCK_CLOSE); + if (found === null) return content; + + lines[found.openLine] = lines[found.openLine].replace(LEGACY_BLOCK_OPEN, BLOCK_OPEN); + lines[found.closeLine] = lines[found.closeLine].replace(LEGACY_BLOCK_CLOSE, BLOCK_CLOSE); + return lines.join("\n"); +} + +// A file carrying one marker without its pair can never be filled again. Say so: +// silence about a block that does not sync is what kept the memory unloaded. +function reportUnpairedMarkers(filePath, content) { + const has = (marker) => content.includes(marker); + const unpaired = + has(BLOCK_OPEN) !== has(BLOCK_CLOSE) || + has(LEGACY_BLOCK_OPEN) !== has(LEGACY_BLOCK_CLOSE); + + if (unpaired) { + console.error(`update_memory: ${filePath} has an unpaired project memory marker, not synced`); + } + return unpaired; +} + +function updateBlock(content, innerContent) { + return updateMarkers(content, BLOCK_OPEN, BLOCK_CLOSE, innerContent); +} + +// memory/-relative path, e.g. aidd_docs/memory/internal/x.md -> internal/x.md. +function memoryRelative(path, filePath) { + return filePath.replace(/\\/g, "/").replace(`${memoryPath(path)}/`, ""); +} + +// Human-facing TOC of the memory bank, grouped by load tier. +function buildToc(rootFiles, onDemandFiles, path) { + const link = (f) => { + const rel = memoryRelative(path, f); + return `- [${rel}](${rel})`; + }; + const lines = rootFiles.map(link); + if (onDemandFiles.length > 0) { + lines.push("", "Read on demand:", "", ...onDemandFiles.map(link)); + } + if (lines.length === 0) lines.push("_No memory files yet._"); + return `\n${lines.join("\n")}\n`; +} + +// The context files to fill. No tool named: every target already present, which +// is what the auto hook wants. Tools named: only theirs, so an AGENTS.md the +// user never picked keeps its block untouched. +function resolveTargets(tools) { + if (tools.length === 0) return TARGET_FILES; + + const unknown = tools.filter((t) => !(t in TOOL_FILES)); + if (unknown.length > 0) { + const known = Object.keys(TOOL_FILES).join(", "); + console.error(`update_memory: unknown tool ${unknown.join(", ")} (known: ${known})`); + process.exit(1); + } + + const wanted = new Set(tools.map((t) => TOOL_FILES[t])); + return TARGET_FILES.filter((target) => wanted.has(target.path)); +} + +function gitAdd(childProcess, files) { + try { + childProcess.execSync(`git add ${files.map((f) => `"${f}"`).join(" ")}`, { + stdio: ["pipe", "pipe", "pipe"], + }); + } catch { + // silent: no git or not a repo + } +} + +// ── Main ────────────────────────────────────────────────────────── + +// Runs as a script, never imported: no require, no module.exports, and every +// dependency pulled in with dynamic import(). The file is copied into the user's +// project by the CLI, so a project declaring "type": "module" decides how it is +// parsed. CommonJS syntax here would crash the hook on load in any such project. +(async () => { + const fs = await import("node:fs"); + const path = await import("node:path"); + const childProcess = await import("node:child_process"); + + // Every path below is project-relative, so anchor on the project root when + // Claude Code names it. Without this a run started elsewhere finds no bank + // and exits 0, which reads as success. + const root = process.env.CLAUDE_PROJECT_DIR; + if (root && fs.existsSync(root)) process.chdir(root); + + if (!fs.existsSync(DOCS_DIR)) process.exit(0); + + const tools = process.argv.slice(2).map((arg) => arg.toLowerCase()); + const targets = resolveTargets(tools); + + const rootFiles = scanRootFiles(fs, path); + const onDemandFiles = ON_DEMAND_DIRS.flatMap((sub) => scanSubdir(fs, path, sub)); + const changed = []; + let unpaired = false; + + for (const target of targets) { + const original = readTextOrNull(fs, target.path); + if (original === null) continue; + + const innerContent = buildBlockContent(rootFiles, onDemandFiles, target.syntax); + // Compare against what is on disk, not against the migrated text: a file + // whose memory list is unchanged would otherwise look identical and skip + // the write, leaving the legacy markers in place forever. + const updated = updateBlock(migrateLegacyMarkers(original), innerContent); + + if (updated === null) { + if (reportUnpairedMarkers(target.path, original)) unpaired = true; + continue; + } + if (updated === original) continue; + + fs.writeFileSync(target.path, updated, "utf8"); + changed.push(target.path); + } + + // Refresh the human-facing TOC in memory/README.md, only if it opts in with markers. + const readmePath = memoryPath(path, MEMORY_README); + const readmeOriginal = readTextOrNull(fs, readmePath); + if (readmeOriginal !== null) { + const toc = buildToc(rootFiles, onDemandFiles, path); + const updated = updateMarkers(readmeOriginal, TOC_OPEN, TOC_CLOSE, toc); + if (updated !== null && updated !== readmeOriginal) { + fs.writeFileSync(readmePath, updated, "utf8"); + changed.push(readmePath); + } + } + + // Stage only when running as the auto hook, which owns no other change. Called + // by the skill, generate has just written files this script knows nothing about, + // so staging its own two would leave a partial index that reads like the whole + // change. The skill reports instead, and the user stages what they mean to commit. + if (changed.length > 0 && tools.length === 0) gitAdd(childProcess, changed); + + // Only when tools were named, which means the skill called us and its sync + // action stops on a non-zero exit. The auto hook must never fail a session + // start over a file the user has yet to repair. + if (unpaired && tools.length > 0) process.exit(1); +})(); diff --git a/aidd-context/skills/00-onboard/SKILL.md b/aidd-context/skills/00-onboard/SKILL.md new file mode 100644 index 000000000..443914f1c --- /dev/null +++ b/aidd-context/skills/00-onboard/SKILL.md @@ -0,0 +1,32 @@ +--- +name: 00-onboard +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +argument-hint: project +--- + +# Onboard + +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` + +## Actions + +Run the actions in that order, looping. Read an action's file in `actions/` before running it. + +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | + +## Transversal rules + +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. diff --git a/aidd-context/skills/00-onboard/actions/01-scan.md b/aidd-context/skills/00-onboard/actions/01-scan.md new file mode 100644 index 000000000..23bd0e70f --- /dev/null +++ b/aidd-context/skills/00-onboard/actions/01-scan.md @@ -0,0 +1,27 @@ +# 01 - Scan + +Read the project into a snapshot. + +## Input + +The project root. + +## Output + +The project snapshot, printed nowhere. + +## Process + +1. **Zones.** Evaluate the checks per [zones.md](../references/state/zones.md). +2. **Detect.** Resolve AI tools and wiring per [detection.md](../references/state/detection.md). +3. **Ledger.** Drop done steps per [done-rule.md](../references/state/done-rule.md). +4. **Hedge.** If a plan exists, pin the build-to-ship stage per [hedge.md](../references/state/hedge.md). +5. **List.** Gather installed AIDD plugins and skills via native discovery. +6. **Hold.** Keep the snapshot in context. Print nothing. + +## Test + +- Scan prints nothing. +- The snapshot carries a status per check. +- It carries the detected AI tools with wiring, and the installed skills. +- A ledgered step and a cross-branch PR never enter the snapshot's actionable set. diff --git a/aidd-context/skills/00-onboard/actions/02-assess.md b/aidd-context/skills/00-onboard/actions/02-assess.md new file mode 100644 index 000000000..57d1ad510 --- /dev/null +++ b/aidd-context/skills/00-onboard/actions/02-assess.md @@ -0,0 +1,25 @@ +# 02 - Assess + +Turn the snapshot into one decision. + +## Input + +The project snapshot. + +## Output + +The decision, ready to render. + +## Process + +1. **Classify.** State class per [screen-map.md](../references/order/screen-map.md). +2. **Rank.** Top next action per [ranking.md](../references/order/ranking.md). + - Idle: build the menu per [idle-menu.md](../references/order/idle-menu.md). +3. **Resolve.** Match each command to an installed skill. + - Absent: name a gap by function, never invent a command. + +## Test + +- Assess renders nothing. +- Dev-flow, health, and idle stay back while a foundation is unmet. +- An idle decision offers the three umbrellas plus explore. diff --git a/aidd-context/skills/00-onboard/actions/03-present.md b/aidd-context/skills/00-onboard/actions/03-present.md new file mode 100644 index 000000000..ec479950e --- /dev/null +++ b/aidd-context/skills/00-onboard/actions/03-present.md @@ -0,0 +1,40 @@ +# 03 - Present + +Render the screen the decision names. + +## Input + +The current decision. + +## Output + +The rendered screen, and the user's reply. + +## Process + +1. **Shape.** Fill the chosen screen from [report.md](../assets/report.md). + - Framing line on the first report of the session only. + - Exactly one action block per screen, carrying its key once. + - The idle menu is a next-action block. Slot 1 is the action line, slots 2 to 4 join the options line. Never a list. + - The state block carries every foundation, so the foundations step count reads off it. + - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. + - A used tool that lacks the block is `⚠️`, never `❌`. Only a missing required foundation takes `❌`. + - Every `⚠️` shows its cause and a keyed fix. + - Short lines. + - The options line is the last line. Print nothing after it, no detail block, no state snapshot, no hint about what comes next. + - Command ids, tier clauses, and lookahead only under `[d]`. + - Keys are letters or digits. Never `?`, `!`, `/`, `@`, `#`: the host takes those. +2. **Inject.** + - Entry screen takes [banner.txt](../assets/banner.txt). + - Flow or walk screen loads [flow.md](../references/flow.md). +3. **Wait.** Offer the screen, take the reply. + +## Test + +- The framing line shows on the first report of the session only. +- An existing repo renders memory as step 1 of 2. +- A greenfield repo renders the stack first. +- The banner shows on entry screens only. +- Every `⚠️` carries a keyed fix. +- The key appears once per screen. +- Nothing renders after the options line. diff --git a/aidd-context/skills/00-onboard/actions/04-run.md b/aidd-context/skills/00-onboard/actions/04-run.md new file mode 100644 index 000000000..d72470913 --- /dev/null +++ b/aidd-context/skills/00-onboard/actions/04-run.md @@ -0,0 +1,33 @@ +# 04 - Run + +Carry out the reply. + +## Input + +- The user's reply, per [replies.md](../references/run/replies.md). +- The current decision, its resolved commands or a gap. + +## Output + +The reply carried out. + +## Process + +1. **Route.** Carry out the reply per [replies.md](../references/run/replies.md). +2. **Guard.** + - Run only installed skills. + - A gap invokes nothing. + - A MANUAL step is shown, not run. +3. **Tier.** Running a step, apply [tiers.md](../references/run/tiers.md). +4. **Return.** On a GUIDED handoff, emit the return line per [return.md](../references/run/return.md). +5. **Record.** Write the handled step to the ledger per [done-rule.md](../references/state/done-rule.md). +6. **Loop.** After a run or `OK` walk, re-scan. + - A read-only reply or umbrella pick does not. + +## Test + +- `OK` runs AUTO unattended and pauses at each GUIDED. +- A MANUAL step is shown, never run. +- A gap invokes nothing. +- `d`/`back` re-render with no re-scan. +- A GUIDED handoff emits the return line. diff --git a/aidd-context/skills/00-onboard/assets/banner.txt b/aidd-context/skills/00-onboard/assets/banner.txt new file mode 100644 index 000000000..422836232 --- /dev/null +++ b/aidd-context/skills/00-onboard/assets/banner.txt @@ -0,0 +1,7 @@ + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development 🇫🇷 diff --git a/aidd-context/skills/00-onboard/assets/report.md b/aidd-context/skills/00-onboard/assets/report.md new file mode 100644 index 000000000..e100e2b7c --- /dev/null +++ b/aidd-context/skills/00-onboard/assets/report.md @@ -0,0 +1,66 @@ + + +## Entry — greenfield · existing · idle · drift + +```txt + + +👋 + +Your AIDD setup: + AI tools + Plugins ✅ + Tech stack <✅ established | ❌ not chosen yet> + Memory + + + + + · flow [m] +``` + +## Action block — foundations step + +```txt +Foundations — step of + + + () + + — > + +👉 Type [1] to start. skip [s] +``` + +## Action block — warning with a fix + +```txt +⚠️ + → Type [1] to . +``` + +## Action block — next action + +```txt +👉 [1] +``` + +## Where you are — mid-work + +```txt +🔍 + + Flow: + +👉 Next: [1] + +``` + +## [d] detail + +```txt +Details — + 1. () + + explain · explain project · recap · stop · back [b] +``` diff --git a/aidd-context/skills/00-onboard/references/flow.md b/aidd-context/skills/00-onboard/references/flow.md new file mode 100644 index 000000000..88a9eb697 --- /dev/null +++ b/aidd-context/skills/00-onboard/references/flow.md @@ -0,0 +1,27 @@ +# AIDD flow curriculum + +## Foundations (state-aware) + +- Existing (code present): memory first, stack skipped. `project memory` → `connect to the AI`. +- Greenfield (empty): `design tech stack` → `project memory` → `connect to the AI`. + +## Feature flow — 8 steps + +| Step | What | Why | +| ------------ | --------------------------- | ------------------------------ | +| brainstorm | vague idea → precise | fuzzy idea makes every step guess | +| spec* | the contract of what to build | one agreed definition, no drift | +| plan | break into phases | small units that ship + verify | +| implement | build phase by phase | verified phases beat one leap | +| assert | check it behaves | catch breakage before review | +| review | verdict before shipping | ship or iterate, decided | +| commit | save the work | atomic, reversible record | +| pull request | ship it | open for merge | + +`[map]`: `brainstorm → spec* → plan → implement → assert → review → commit → PR` + +`*`: optional + +## Run it + +`[1]` walk with me, step by step · `[2]` hand the whole flow to `aidd-orchestrator:01-sdlc` diff --git a/aidd-context/skills/00-onboard/references/order/idle-menu.md b/aidd-context/skills/00-onboard/references/order/idle-menu.md new file mode 100644 index 000000000..3358ed8ad --- /dev/null +++ b/aidd-context/skills/00-onboard/references/order/idle-menu.md @@ -0,0 +1,14 @@ +# Idle menu + +When ranks 1-3 are clear, the idle menu offers four choices. + +| Slot | Choice | Opens (installed members) | +| ---- | ------------------- | -------------------------------------------------------------------- | +| 1 | start new work | `aidd-orchestrator:01-sdlc`, or `aidd-refine:01-brainstorm` for a fuzzy idea | +| 2 | improve the project | `aidd-dev:` `04-audit` · `06-test` · `07-refactor` | +| 3 | customize the AI | the **missing** `aidd-context:` generators: rule `05-rule-generate`, workflow `04-skill-generate`, agent `06-agent-generate`, command `07-command-generate`, hook `08-hook-generate` | +| 4 | explore | `aidd-context:11-explore` + anything not in 1-3 | + +- Slots 2 and 3 are umbrellas: a pick re-renders the member sub-list, a member pick runs. Slots 1 and 4 run directly. +- Installed members only. Drop an empty umbrella. +- Choices, not a chain: `OK` never walks the idle menu. diff --git a/aidd-context/skills/00-onboard/references/order/ranking.md b/aidd-context/skills/00-onboard/references/order/ranking.md new file mode 100644 index 000000000..d62a726f1 --- /dev/null +++ b/aidd-context/skills/00-onboard/references/order/ranking.md @@ -0,0 +1,10 @@ +# Next-action order + +First match wins. + +1. Unmet foundation, in `zones.md` order. +2. Earliest unmet dev-flow stage, hedged by `state/hedge.md`. +3. A fired health tool. +4. Idle menu (see `idle-menu.md`) — only when 1-3 are all clear. + +While any foundation is unmet, hold 2-4 back: a bare repo lists only its setup steps. diff --git a/aidd-context/skills/00-onboard/references/order/screen-map.md b/aidd-context/skills/00-onboard/references/order/screen-map.md new file mode 100644 index 000000000..0637cff48 --- /dev/null +++ b/aidd-context/skills/00-onboard/references/order/screen-map.md @@ -0,0 +1,9 @@ +# Screen map + +| State class | When | Screen | +| ----------- | ---------------------------- | --------------------------------------------------- | +| greenfield | no code, no memory | welcome + foundations, stack first (3 steps) | +| existing | code present, memory missing | welcome + foundations, memory first (2 steps) | +| drift | a foundation is ⚠ | welcome + the warning-with-fix | +| midwork | a dev-flow step pending | where-you-are on the flow + the next step | +| idle | all clear | welcome + the flow (walk or SDLC), or the idle menu | diff --git a/aidd-context/skills/00-onboard/references/run/replies.md b/aidd-context/skills/00-onboard/references/run/replies.md new file mode 100644 index 000000000..9108bf7c6 --- /dev/null +++ b/aidd-context/skills/00-onboard/references/run/replies.md @@ -0,0 +1,14 @@ +# Replies + +| Reply | Effect | +| ------------- | --------------------------------------------------------------------------------- | +| a number `[n]`| run that step, or open an idle-menu umbrella | +| `OK` | walk the pending steps (ranks 1-3) in order, never the idle menu | +| `d` / `details` | expand the full detail (command ids, tier clauses, per-check reasons), read-only | +| `b` / `back` | re-render the prior screen, read-only, no re-scan | +| `recap` | summarize this session's conversation, read-only, only when a prior conversation exists | +| `explain ` | describe a step in two or three plain lines, read-only | +| `explain project` | summarize the project from its memory bank, read-only, only when memory is filled | +| `skip` | record the step left in the ledger, it does not re-fire | +| `stop` | one-line close, end the loop | +| a gap | no installed skill, say it needs a plugin by function, offer explain or stop | diff --git a/aidd-context/skills/00-onboard/references/run/return.md b/aidd-context/skills/00-onboard/references/run/return.md new file mode 100644 index 000000000..8654e2874 --- /dev/null +++ b/aidd-context/skills/00-onboard/references/run/return.md @@ -0,0 +1,3 @@ +# Return to onboard + +A GUIDED step hands off to a skill that may not return control. So on every handoff, tell the user one line: re-run onboard to come back (the sure path is its slash command). The re-scan drops the handed-off step, so they resume, not repeat. diff --git a/aidd-context/skills/00-onboard/references/run/tiers.md b/aidd-context/skills/00-onboard/references/run/tiers.md new file mode 100644 index 000000000..da28cedf2 --- /dev/null +++ b/aidd-context/skills/00-onboard/references/run/tiers.md @@ -0,0 +1,13 @@ +# Tiers + +The tier is a default, overridable. + +| Tier | Clause | How it runs | +| ------ | --------------------------------- | ------------------------------------------------------------ | +| AUTO | (runs on its own) | invoke, run to completion, continue | +| GUIDED | (it will ask you a few questions) | launch, hand to the user, resume on return (see `return.md`) | +| MANUAL | (you run this one yourself) | show the command, run nothing, leave it for the user | + +- A dual-mode skill runs the other way when the user asks and the skill supports it. +- `aidd-orchestrator:01-sdlc` is autonomous by contract; do not downgrade it to `GUIDED`. +- On the `OK` walk, state up front how many steps it covers and which need input. diff --git a/aidd-context/skills/00-onboard/references/state/detection.md b/aidd-context/skills/00-onboard/references/state/detection.md new file mode 100644 index 000000000..f66011153 --- /dev/null +++ b/aidd-context/skills/00-onboard/references/state/detection.md @@ -0,0 +1,18 @@ +# AI tool detection + +Which AI tools the project uses, and whether each has its memory wired. For the state block's AI-tools line. + +A tool is used when its own dir exists, or when a file only that tool reads exists. A file several tools read (`AGENTS.md`) is a wiring target, never a detection signal. + +| Tool | Used when | Wired when this file has the block | +| -------- | ------------------------------------------------------------------------------------ | ---------------------------------- | +| claude | `.claude/` or `CLAUDE.md` | `CLAUDE.md` | +| codex | `.codex/` | `AGENTS.md` | +| cursor | `.cursor/` or `.cursorrules` | `AGENTS.md` | +| opencode | `.opencode/` | `AGENTS.md` | +| copilot | `.github/copilot-instructions.md` or `.github/{instructions,agents,skills,prompts}/` | `.github/copilot-instructions.md` | + +- Detected tools only. An unused optional tool is omitted, never crossed. +- No tool detected at all: the row reads `none yet`, uncrossed. The memory row's `❌` already carries the gap. +- A used tool whose file lacks the block is not wired, and needs wiring. +- Missing memory is a foundation status, not a tool row (see `zones.md`). diff --git a/aidd-context/skills/00-onboard/references/state/done-rule.md b/aidd-context/skills/00-onboard/references/state/done-rule.md new file mode 100644 index 000000000..9070e4d44 --- /dev/null +++ b/aidd-context/skills/00-onboard/references/state/done-rule.md @@ -0,0 +1,6 @@ +# Done rule (session ledger) + +Stops onboard from re-recommending a step already handled this session. In-context state, no file. + +- Done = a disk signal proves it, OR the ledger recorded it run or left (a read-only review, a MANUAL step left, a skip). +- Re-read every scan, so a step recorded since drops out. Disk and VCS facts refresh on change, not every loop. diff --git a/aidd-context/skills/00-onboard/references/state/hedge.md b/aidd-context/skills/00-onboard/references/state/hedge.md new file mode 100644 index 000000000..fe44590da --- /dev/null +++ b/aidd-context/skills/00-onboard/references/state/hedge.md @@ -0,0 +1,12 @@ +# Plan-status hedge + +The plan's `status:` frontmatter refines the build-to-ship pin, so review is never skipped nor premature. + +| Plan `status:` | Pin | +| ---------------------------- | ------------------------------------- | +| `pending` | To implement | +| `in-progress` | Implement alone | +| `implemented` | Review | +| `reviewed` | Ship (commit, pull request) | +| `blocked` | surface the blocker, not a normal pin | +| the field is missing or unreadable | surface the plan as broken, not a normal pin | diff --git a/aidd-context/skills/00-onboard/references/state/zones.md b/aidd-context/skills/00-onboard/references/state/zones.md new file mode 100644 index 000000000..ead0a597b --- /dev/null +++ b/aidd-context/skills/00-onboard/references/state/zones.md @@ -0,0 +1,41 @@ +# State zones + +Disk/VCS checks that place the project. Each check is met, drift (present, off canonical shape), or missing. + +## Foundations + +State-aware order: existing repo (code) => memory first, stack skipped. Greenfield => stack → memory → wire. + +| Check | Met when | Drift when | Deliverable | Command | +| -------------- | ------------------------------------------------------------- | ------------------------ | -------------------------- | -------------------------------- | +| tech stack | `INSTALL.md` exists OR repo established (code or synced memory) | — | tech stack | `aidd-context:01-bootstrap` | +| project memory | `aidd_docs/memory/` has real content | files empty/placeholder | project knowledge saved | `aidd-context:02-project-memory` | +| memory wiring | the standard project memory block in each used tool's context file | block present, off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | + +- tech stack missing only on greenfield (no code AND no synced memory). +- memory wiring: no block or no context file = missing. Drift = a block present but not the standard one that imports the memory files. + +## Dev flow + +Cumulative: a downstream artifact implies the upstream stages met. The pin sits on the furthest reached. + +| Stage | Detected when | +| --------- | --------------------------------------------- | +| spec | a spec under `aidd_docs/`, nothing downstream | +| plan | `plan.md`, no code against it | +| implement | code against the plan | +| review | code done, current branch PR awaits review | +| PR | current branch has an open PR | + +- `review` and `PR` read VCS **current branch only** — ignore repo-wide PRs and review queues (another branch is another dev). +- `brainstorm`, `assert`, and `commit` have no cheap signal. The plan `status:` hedge and cumulative state place the pin (see `hedge.md`). + +## Health + +Beside-the-flow tools, surfaced only when their signal fires. Scan project source only, not templates, fixtures, examples, generated output, or installed-plugin trees. + +| Signal | Fires when | Command | +| ----------- | ------------------------------------------- | ------------------- | +| no tests | no real test files | `aidd-dev:06-test` | +| bug markers | `TODO`/`FIXME` or reported errors in source | `aidd-dev:08-debug` | +| messy code | a file far longer/deeper than siblings | `aidd-dev:04-audit` | diff --git a/aidd-context/skills/01-bootstrap/SKILL.md b/aidd-context/skills/01-bootstrap/SKILL.md new file mode 100644 index 000000000..e4db4a84a --- /dev/null +++ b/aidd-context/skills/01-bootstrap/SKILL.md @@ -0,0 +1,39 @@ +--- +name: 01-bootstrap +description: Design and validate a new SaaS's architecture into an INSTALL.md via Q&A and stack comparison. Use when the user starts a project, chooses a stack, or picks an architecture pattern. Not for editing an existing stack or scaffolding code. +argument-hint: idea +--- + +# Bootstrap + +Plays the role of technical architect for a new SaaS project. Walks the user through a 24-item checklist (18 user-input + 6 derived), proposes 2-3 candidate stacks, audits each via parallel agents, then produces `aidd_docs/INSTALL.md` capturing the technical vision, decisions, stack, architecture pattern, folder tree, and install steps. Documentation only: no code, no scaffolding. + +## Actions + +| # | Action | Role | Input | +| --- | --------------------- | -------------------------------------------------------------- | ------------------ | +| 01 | `gather-needs` | Q&A across the 24-item checklist | user intent | +| 02 | `propose-candidates` | Derive 2-3 candidate stacks, render comparison table | filled checklist | +| 03 | `audit-candidates` | Spawn parallel agents to validate each candidate, emit verdict | candidates table | +| 04 | `pick-and-design` | User picks winner; generate folder tree + Mermaid diagram | audit report | +| 05 | `write-install-md` | Produce `aidd_docs/INSTALL.md` | design + decisions | + +Run `01 → 02 → 03 → 04 → 05`. The audit (03) gates: if every candidate fails, loop back to 02 or 01. +Before running an action, read its file in `actions/`, not only the table or assets. + +## Transversal rules + +- **No file scaffolding.** This skill writes only `aidd_docs/INSTALL.md`. It never creates `package.json`, source files, or empty directories. +- **Anti-sycophancy.** When the user expresses a stack preference that conflicts with their needs (e.g. wants Mongo for heavily relational data), challenge it before accepting: surface audit concerns and ask whether the user has a mitigation plan. +- **Recommend opinionated, not encyclopedic.** Each action proposes 2-3 options max, never a long catalog. The user should leave with a concrete decision, not a research paper. +- **Stop on full checklist.** Action 01 keeps asking until the 18 user-input items (blocks 1-3) are filled; the 6 derived items (block 4) are filled across actions 02 and 04. +- **Apply heuristics from `references/stack-heuristics.md`** when proposing candidates. + +## References + +- `references/stack-heuristics.md` - input → recommended-stack-family heuristics + +## Assets + +- `assets/checklist.md` - the 24-item checklist (4 blocks) +- `assets/install-template.md` - the `INSTALL.md` skeleton diff --git a/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md b/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md new file mode 100644 index 000000000..fd2d08693 --- /dev/null +++ b/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md @@ -0,0 +1,26 @@ +# 01 - Gather needs + +Walk the user through the 24-item checklist via interactive Q&A until all 18 user-input items (blocks 1 to 3) are filled. The 6 derived items (block 4) stay empty here; actions 02 and 04 fill them. + +## Input + +A free-form user request to bootstrap a new SaaS project. + +## Output + +A filled copy of [checklist.md](../assets/checklist.md) held in conversation context, not yet written to disk, with every user-input item's `<...>` placeholder replaced by a concrete value. + +## Process + +1. **Show.** Read [checklist.md](../assets/checklist.md) and print the four blocks as one markdown checklist so the user sees the full scope upfront. +2. **Ask.** Ask block by block, one block per message, all questions in a block at once. Do not ask block 4; it is derived. +3. **Fill.** Fill each item from the answer. When an answer is vague ("scalable", "fast"), ask one follow-up to make it concrete (numbers, examples). +4. **Check.** After block 1, sanity-check coherence: does the type match the user volume, are the integrations realistic for the platform target. +5. **Resolve.** After block 3, surface conflicts (for example budget under 50€/mo with an AWS preference and a heavy backend) and force a re-answer on the conflicting item. +6. **Confirm.** Print the filled checklist (blocks 1 to 3) and wait for the user to confirm "go" before action 02. + +## Test + +- The 18 user-input items have no remaining `<...>` placeholders. +- The 6 block-4 items are still placeholders. +- The user explicitly confirmed the filled checklist before action 02 starts. diff --git a/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md b/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md new file mode 100644 index 000000000..d7166378b --- /dev/null +++ b/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md @@ -0,0 +1,26 @@ +# 02 - Propose candidates + +Derive 2 to 3 candidate stacks from the filled checklist, then render a markdown comparison table. + +## Input + +The filled checklist (blocks 1 to 3) from action 01. + +## Output + +A markdown comparison table with 2 to 3 rows, each a candidate with its front, back, DB, hosting, auth, architecture pattern, monthly cost, and risks. + +## Process + +1. **Read.** Read the filled checklist from action 01. +2. **Derive.** Apply each rule from [stack-heuristics.md](../references/stack-heuristics.md) to derive the recommended family for architecture pattern, front, back, DB, auth, and hosting. +3. **Spread.** Build 2 to 3 candidates spanning the trade-off space, differing on at least one of hosting model (PaaS, self-host, serverless), back-end language, or architecture pattern. Never propose near-identical candidates. +4. **Cost.** Estimate each candidate's monthly cost at the user's six-month volume target with rough public pricing, flagging uncertainty. +5. **Risk.** List 1 to 3 honest risks per candidate (lock-in, ops burden, learning curve, scaling limit). No candidate has zero. +6. **Render.** Render the comparison table, bolding each candidate's name. Do not pick a winner; that is action 04, after the audit. + +## Test + +- The output is a markdown table with at least two rows. +- The columns include front, back, DB, hosting, auth, architecture, cost, and risks, each cell non-empty. +- At least two rows differ on hosting model, back-end language, or architecture pattern. diff --git a/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md b/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md new file mode 100644 index 000000000..d96bc8b81 --- /dev/null +++ b/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md @@ -0,0 +1,38 @@ +# 03 - Audit candidates + +Audit each candidate in parallel to validate the proposed stack: tech compatibility, ecosystem maturity, known gotchas. Returns a verdict (✅ / ⚠️ / ❌) and a three-bullet rationale per candidate. + +## Input + +The comparison table from action 02, and the filled checklist from action 01 for context. + +## Output + +The action 02 table augmented with a verdict column, plus a three-bullet rationale block per candidate. + +## Process + +1. **Audit.** For each candidate row, spawn a parallel `general-purpose` agent with this brief: + + ```text + Audit the following candidate stack for a SaaS project. Validate three dimensions: + 1. Tech compatibility: do the components integrate cleanly? Any deprecated combos? + 2. Ecosystem maturity: are the components stable (≥ 2 years prod-tested) and well-documented? + 3. Known gotchas: search recent (last 12 months) issues, blog posts, and discussions for blockers. + + Project context: + Candidate: + + Return: + - Verdict: ✅ (no blocker) / ⚠️ (minor concerns) / ❌ (deal-breaker) + - Three bullets justifying the verdict, concrete, citing specific tech facts, one of them stating whether the proposed monthly cost is realistic + ``` + +2. **Aggregate.** Wait for every agent to return, then aggregate the verdicts into the table. +3. **Gate.** When every candidate returns ❌, print the verdicts, surface the common blocker, and loop back to action 02, or to 01 when the needs themselves are the blocker, with explicit guidance. Do not proceed to action 04. +4. **Pass.** When at least one candidate is ✅ or ⚠️, print the augmented table and per-candidate rationale, then pass control to action 04. + +## Test + +- Each candidate row has a verdict in `{✅, ⚠️, ❌}` and a rationale block of exactly three bullets. +- When every verdict is ❌, the flow does not advance to action 04 and prints guidance back to action 02. diff --git a/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md b/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md new file mode 100644 index 000000000..4859ccfc9 --- /dev/null +++ b/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md @@ -0,0 +1,26 @@ +# 04 - Pick and design + +The user picks the winning candidate, informed by the audit. Generate the folder-structure tree and a Mermaid module diagram, and fill block 4 of the checklist with the concrete choices. + +## Input + +The augmented comparison table from action 03 (verdicts and rationale), and the filled checklist blocks 1 to 3. + +## Output + +Three artifacts held in conversation context: the checklist with block 4 filled (architecture pattern, front, back, DB, auth, final hosting), a folder-structure code block of the project root tree, and a Mermaid diagram of the modules and their relations. + +## Process + +1. **Pick.** Print the action 03 augmented table and ask the user to pick a candidate by name. +2. **Vet.** On a ⚠️ pick, surface the audit concerns, ask for a mitigation plan, and loop until satisfied or the pick changes. On a ❌ pick, refuse and loop back; never proceed with a known-broken stack. +3. **Fill.** Fill block 4 with the picked candidate's concrete choices, show the full checklist, and wait for the user to confirm "go". +4. **Tree.** Generate the folder-structure tree following the picked stack's conventions: a monorepo (`apps/`, `packages/`) for a modular monolith, a flat `src/` for a monolith, `services/` per service for microservices, `functions/` for serverless. Reflect every block-4 component. +5. **Diagram.** Generate the Mermaid module diagram via a Mermaid-rendering capability, passing the modules and relations from the tree, and confirm it parses without error. +6. **Show.** Print the tree and diagram together, then wait for confirmation before action 05. + +## Test + +- Block 4 has all six items filled with no remaining `<...>` placeholders. +- A folder-structure code block is rendered, and a fenced `mermaid` block is present and parses without error. +- The user confirmed in writing. diff --git a/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md b/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md new file mode 100644 index 000000000..b73a246c0 --- /dev/null +++ b/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md @@ -0,0 +1,31 @@ +# 05 - Write INSTALL.md + +Produce `aidd_docs/INSTALL.md` from the filled checklist, folder tree, diagram, and audit summary. The only file this skill writes to disk. + +## Input + +The filled checklist, folder-structure code block, and Mermaid diagram from action 04, and the augmented audit table from action 03. + +## Output + +A new `aidd_docs/INSTALL.md` filled from [install-template.md](../assets/install-template.md), with its Vision, Decisions, Stack summary, Architecture, Folder structure, Install steps, and Audit summary sections. + +## Process + +1. **Load.** Read [install-template.md](../assets/install-template.md) as the skeleton. +2. **Fill.** Fill each placeholder from the upstream artifacts: + - **Vision**: project name and one-liner from block 1. + - **Decisions**: each block-4 row paired with a one-line why from the block 2 and 3 constraints. + - **Stack summary**: concrete versions or SaaS plans where known. + - **Architecture**: the action 04 Mermaid diagram plus two or three sentences on module boundaries. + - **Folder structure**: the action 04 tree verbatim. + - **Install steps**: 3 to 7 imperative steps to bring up the empty project (init repo, install runtimes, create cloud accounts, set env vars). A checklist, not a script, with no code generation. + - **Audit summary**: the action 03 augmented table, keeping verdicts and one-line notes. +3. **Write.** Write the filled content to `aidd_docs/INSTALL.md` in the project root. When the file already exists, ask before overwriting. +4. **Report.** Print the written file's relative path and a short summary of the sections filled and total length. + +## Test + +- `aidd_docs/INSTALL.md` exists and parses as markdown. +- It contains these H2 headings in order: Vision, Decisions, Stack summary, Architecture, Folder structure, Install steps, Audit summary. +- The Architecture section contains a fenced `mermaid` block, and the Folder structure section a fenced code block of at least five lines. diff --git a/aidd-context/skills/01-bootstrap/assets/checklist.md b/aidd-context/skills/01-bootstrap/assets/checklist.md new file mode 100644 index 000000000..d539fbc98 --- /dev/null +++ b/aidd-context/skills/01-bootstrap/assets/checklist.md @@ -0,0 +1,39 @@ +# Bootstrap checklist + +24 items across 4 blocks. Blocks 1-3 are filled by user input (action 01). Block 4 is derived and validated across actions 02 and 04. + +## 📌 Block 1 - Project (the what) + +- [ ] **Project name** - `` +- [ ] **One-liner** - `` +- [ ] **Type** - `` +- [ ] **Target users** - `` +- [ ] **Top 3-5 features** - `` +- [ ] **External integrations** - `` +- [ ] **Target platform** - `` + +## ⚙️ Block 2 - Technical constraints (drive stack choice) + +- [ ] **Real-time?** - `` +- [ ] **Multi-tenant?** - `` +- [ ] **Data sensitivity** - `` +- [ ] **Volume at 6 months** - `` +- [ ] **SEO important?** - `` +- [ ] **Performance target** - `` +- [ ] **Offline mode?** - `` + +## 🛠️ Block 3 - Team preferences & constraints + +- [ ] **Languages mastered by team** - `` +- [ ] **Hosting budget** - `` +- [ ] **Hosting preference** - `` +- [ ] **Deal-breakers** - `` + +## 🎯 Block 4 - Derived choices (output, validated by user) + +- [ ] **Architecture pattern** - `` +- [ ] **Front-end** - `` +- [ ] **Back-end** - `` +- [ ] **Database** - `` +- [ ] **Auth provider** - `` +- [ ] **Final hosting** - `` diff --git a/aidd-context/skills/01-bootstrap/assets/install-template.md b/aidd-context/skills/01-bootstrap/assets/install-template.md new file mode 100644 index 000000000..cb2c22e5b --- /dev/null +++ b/aidd-context/skills/01-bootstrap/assets/install-template.md @@ -0,0 +1,63 @@ +# INSTALL.md - `` + +Technical vision and installation guide. + +## Vision + +`` + +`<2-3 sentences expanding on the value proposition, target users, and core differentiator>` + +## Decisions + +| Decision | Choice | Why | +| ------------------ | ----------------- | -------------------------------------------------- | +| Architecture | `` | `` | +| Front-end | `` | `` | +| Back-end | `` | `` | +| Database | `` | `` | +| Auth | `` | `` | +| Hosting | `` | `` | + +## Stack summary + +- **Front-end:** `` +- **Back-end:** `` +- **Database:** `` +- **Auth:** `` +- **Hosting:** `` +- **Key integrations:** `` + +## Architecture + +```mermaid + +``` + +`<2-3 sentences explaining the diagram: which modules talk to which, where the boundary is>` + +## Folder structure + +``` +/ +├── ... +└── ... +``` + +## Install steps + +Manual install - the framework does not yet scaffold these automatically. + +1. `` +2. `` +3. `` + +## Audit summary + +Results of the multi-agent audit run during action 03: + +| Candidate | Verdict | Notes | +| -------------------- | ------- | ------------------------------ | +| `` | ✅ / ⚠️ / ❌ | `` | +| `` | ✅ / ⚠️ / ❌ | `` | +| `` | ✅ / ⚠️ / ❌ | `` | diff --git a/aidd-context/skills/01-bootstrap/references/stack-heuristics.md b/aidd-context/skills/01-bootstrap/references/stack-heuristics.md new file mode 100644 index 000000000..ee8632e4d --- /dev/null +++ b/aidd-context/skills/01-bootstrap/references/stack-heuristics.md @@ -0,0 +1,75 @@ +# Stack heuristics + +Mapping rules from checklist signals to recommended stack families. Use these when proposing candidates in action 02. Heuristics, not laws - override when audit (action 03) flags a conflict. + +## Architecture pattern + +| Signal (from checklist) | Pattern | +| ---------------------------------------------------------------------- | ---------------------- | +| Solo or 2-dev team, < 10k users, < 5 features, no real-time | **Monolith** | +| Mid-size team, growing features, want clean modules | **Modular monolith** | +| Many decoupled domains, each with its own scaling profile | **Microservices** | +| Bursty traffic, low ops budget, short-lived requests, no persistent connections | **Serverless** | +| Real-time + low latency required + WebSockets | **Monolith / serverless edge** (avoid pure microservices) | + +## Front-end + +| Signal | Recommendation | +| ----------------------------------------------------------------- | --------------------------------- | +| SEO important + content-heavy | **Next.js SSR** or **Astro SSR** | +| SEO not important + interactive dashboard | **Vite + React SPA** | +| Mobile native required | **React Native / Expo** + web app | +| Marketing site + product app | **Astro (marketing) + Next.js (app)** or **Next.js everything** | +| Offline-first (PWA, local sync) | **Next.js + service worker** or **RxDB-based stack** | + +## Back-end + +| Signal | Recommendation | +| ----------------------------------------------------------------- | --------------------------------- | +| Team knows TypeScript, no exotic perf needs | **Next.js API routes** or **NestJS** | +| Team knows Python, ML/data-heavy | **FastAPI** | +| Team knows Go, high-throughput backend | **Echo / Fiber** | +| Real-time chat, websockets, live sync | **Node + Socket.io** or **Phoenix (Elixir)** | +| Heavy compute (video, ML inference) | **FastAPI + worker queue (Celery / BullMQ)** | + +## Database + +| Signal | Recommendation | +| ----------------------------------------------------------------- | --------------------------------- | +| Relational data, transactions, GDPR | **PostgreSQL** (Supabase, Neon, RDS) | +| Document-shaped data, schema fluctuates often | **MongoDB** or **Postgres JSONB** | +| Existing Airtable as source of truth | **Airtable SDK + Postgres cache layer** | +| Search-heavy (full-text, faceted) | **Postgres + tsvector** OR **Postgres + Meilisearch** | +| Real-time pub/sub | **Supabase Realtime** or **Redis pub/sub** | +| Event sourcing | **Postgres + outbox pattern** | + +## Auth + +| Signal | Recommendation | +| ----------------------------------------------------------------- | --------------------------------- | +| Next.js + Postgres | **NextAuth (Auth.js)** | +| Need polished UI, magic links, OAuth, no time to build | **Clerk** | +| Already on Supabase | **Supabase Auth** | +| Enterprise SSO required | **Auth0** or **WorkOS** | +| B2B with org-level access control | **Clerk Organizations** or **WorkOS** | + +## Hosting + +| Signal | Recommendation | +| ----------------------------------------------------------------- | --------------------------------- | +| Next.js + low ops budget | **Vercel** | +| Solo dev + Postgres + bootstrap budget | **Vercel + Supabase** or **Railway** | +| Heavy backend, custom infra | **AWS (ECS / Fargate)** or **GCP Cloud Run** | +| EU data residency required | **Scaleway**, **OVH**, or AWS eu-west-3 | +| Self-hosted preference | **Coolify** or **Dokku** on VPS | + +## Conflicting-signal triage + +When two signals push to different stacks, prioritize in this order: + +1. **Data sensitivity (GDPR/health)** - overrides hosting region preference +2. **Real-time + multi-tenant** - overrides cost preference (forces non-trivial backend) +3. **Team language expertise** - overrides "best tool" if learning curve > 2 weeks +4. **Budget** - caps everything else; prune candidates that exceed it + +When still ambiguous, surface the trade-off to the user in the comparison table (action 02) instead of choosing silently. diff --git a/aidd-context/skills/02-project-memory/SKILL.md b/aidd-context/skills/02-project-memory/SKILL.md new file mode 100644 index 000000000..e854cb94b --- /dev/null +++ b/aidd-context/skills/02-project-memory/SKILL.md @@ -0,0 +1,33 @@ +--- +name: 02-project-memory +description: Build the project's memory of its architecture, conventions, and decisions, and wire it into your AI tools. Use when the user wants to set up or refresh project memory, or rewire it into a tool. Not for editing one existing memory file. +argument-hint: setup | refresh | rewire +--- + +# Project Memory + +```mermaid +flowchart LR + new([no argument, or setup]) --> scan --> write --> sync --> wired([memory wired]) + update([refresh]) --> scan --> check --> write + rewire([rewire]) --> sync + scan -.-> empty([nothing to remember]) +``` + +## Actions + +Run the flow above, reading only the next action file. + +| Action | Does | +| ------ | ------------------------------- | +| scan | read the project | +| write | write the memory | +| check | show what drifted, change nothing | +| sync | pick the tools, wire it in | + +## Transversal rules + +- If a referenced file cannot be read, stop and say so. Never invent its content. +- Ask before anything ambiguous. Never default silently. +- A bank that already exists changes only through what the user approved, file by file and line by line. +- End with a short report of what changed. diff --git a/aidd-context/skills/02-project-memory/actions/01-scan.md b/aidd-context/skills/02-project-memory/actions/01-scan.md new file mode 100644 index 000000000..d40e45338 --- /dev/null +++ b/aidd-context/skills/02-project-memory/actions/01-scan.md @@ -0,0 +1,30 @@ +# 01 - Scan + +Read the project. + +## Input + +The project root. + +## Output + +The confirmed capabilities and external tools, printed nowhere. + +## Process + +1. **Ground.** Read the project against [reading-sources.md](../references/reading-sources.md), and stop when it holds nothing to read. +2. **Find.** Detect the capabilities per [capability-signals.md](../references/capability-signals.md), each with its evidence. +3. **Map.** Detect the external tools per [ecosystem-signals.md](../references/ecosystem-signals.md), which fill the always-on `ecosystem` capability. +4. **Ask.** Show the scan as [scan-summary.md](../assets/scan-summary.md) does, ask for what the repo cannot prove, and wait. +5. **Confirm.** Keep what the scan found, plus the user's additions, minus their drops. + +## Test + +| Case | Pass | +| --- | --- | +| Completion | no file under the project changed | +| Evidence | the path or dependency named for a capability exists | +| Summary | one row per capability and per tool, each carrying evidence | +| Tool | one access mode per actor that reaches it | +| Every run | the same capabilities for the same repo, bank or no bank | +| Empty repo | the run stops at Ground and hands nothing on | diff --git a/aidd-context/skills/02-project-memory/actions/02-write.md b/aidd-context/skills/02-project-memory/actions/02-write.md new file mode 100644 index 000000000..92a44120a --- /dev/null +++ b/aidd-context/skills/02-project-memory/actions/02-write.md @@ -0,0 +1,30 @@ +# 02 - Write + +Write the memory the project deserves. + +## Input + +The confirmed capabilities, external tools, access modes and hand-offs, plus the findings the user approved when a bank already exists. + +## Output + +The written memory bank. + +## Process + +1. **Scaffold.** Create the tree in [structure.md](../references/structure.md). +2. **Select.** Take the rows to write from [memory-destinations.md](../references/memory-destinations.md). +3. **Write.** Write each row to its destination against [memory-rules.md](../references/memory-rules.md). + - Absent file: fill the template, strip its guidance comment. + - Existing file: apply the approved findings and nothing else. + - A section the file lacks: report it when the project has something for it, never inject it. + +## Test + +| Case | Pass | +| --- | --- | +| Bank written | every selected row exists at its exact path | +| Tree | no `.md` under `memory/` outside `internal/` and `external/`, each holding a `.gitkeep` | +| Memory file | no `TODO` and no `` remains | +| Scaffolded doc | its placeholders are untouched | +| Rerun | only the approved findings changed, every other line survives | diff --git a/aidd-context/skills/02-project-memory/actions/03-check.md b/aidd-context/skills/02-project-memory/actions/03-check.md new file mode 100644 index 000000000..0a81ecf8f --- /dev/null +++ b/aidd-context/skills/02-project-memory/actions/03-check.md @@ -0,0 +1,38 @@ +# 03 - Check + +Show what drifted in the bank, and let the user pick what to fix. Change nothing. + +## Input + +The bank in `aidd_docs/memory/`, and the capabilities the scan found. + +## Output + +A report file under `aidd_docs/tasks/`, a short summary printed, and the findings the user approved. + +## Process + +1. **Match.** Compare the bank against [memory-destinations.md](../references/memory-destinations.md) and [structure.md](../references/structure.md). + - A file no row produces: flag it, and name the row it should have come from. + - A found capability, or a scaffolded path, with nothing on disk: flag it missing. +2. **Review.** Have each memory file reviewed against [review-protocol.md](../references/review-protocol.md) in parallel. +3. **Prune.** Offer to remove each file whose capability the scan did not find, and none when the scan asked nothing. +4. **Report.** Fill [report.md](../assets/report.md), write it to `aidd_docs/tasks//_memory-check/report.md`, and print the summary with that path. + - The folder already holds a report: ask before replacing it. +5. **Offer.** Ask which findings to apply, and hand the approved ones to write. + - Nothing drifted: call the bank current, hand nothing on. + +## Test + +| Case | Pass | +| --- | --- | +| Any run | no file under `aidd_docs/memory/` changed | +| Any finding | the summary holds no table, names the report path, ends on the question | +| Nothing drifted | nothing offered, the bank called current | +| Report | structural gaps and reviewer findings under separate headings | +| Report | no step of this skill named in it | +| Orphan | flagged, with the row it should have come from | +| Missing | a found capability with no file is flagged | +| Contradiction | flagged, the line left in place | +| Duplicate | flagged, both files left as they are | +| Removal declined | the file is still there | diff --git a/aidd-context/skills/02-project-memory/actions/04-sync.md b/aidd-context/skills/02-project-memory/actions/04-sync.md new file mode 100644 index 000000000..e96e752ae --- /dev/null +++ b/aidd-context/skills/02-project-memory/actions/04-sync.md @@ -0,0 +1,34 @@ +# 04 - Sync + +Wire the memory into the tools the user picks. + +## Input + +The memory bank in `aidd_docs/memory/`. + +## Output + +Each picked tool's context file, carrying the filled block. + +## Process + +1. **Require.** Stop unless `aidd_docs/memory/` holds a `.md`, sending the user to write the memory first. +2. **Detect.** Find the AI tools present per [tools.md](../references/tools.md). +3. **Pick.** Show every tool, the detected ones ticked, and wait for one or several. +4. **Upsert.** Ensure each picked tool's context file carries the block, per [tools.md](../references/tools.md). + - Absent file: create it from [AGENTS.md](../assets/templates/AGENTS.md). + - Its AIDD structure differs: offer to reconcile it, applying only what the user approves. +5. **Fill.** Run `hooks/update_memory.js` from the project root, naming the picked tools, and stop on a non-zero exit. + - No script, the skill shipped alone: write each block from the bank. +6. **Verify.** Read each picked tool's block back and compare it to the bank. + - A file in one and not the other: the fill did not land, report it and stop. + +## Test + +| Case | Pass | +| --- | --- | +| Empty bank | no context file created, the run stops | +| Script | it exits `0` | +| Picked tool | its block lists every root `.md` except `README.md`, nothing else | +| Bank grew | the block gains that file and keeps the rest | +| Unpicked tool | its context file is unchanged | diff --git a/aidd-context/skills/02-project-memory/assets/report.md b/aidd-context/skills/02-project-memory/assets/report.md new file mode 100644 index 000000000..4d5225e09 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/report.md @@ -0,0 +1,56 @@ + + +## Printed once, at any terminal width + +```txt +Memory bank — on disk, gaps, findings + + .md missing + .md orphan + .md + .md + + aidd_docs/tasks//_memory-check/report.md +``` + +No table, and one file per line. A terminal is narrow: a table reflows into unreadable blocks, and +so does a line that lists several files. Keep every line under forty characters, the path aside. + +## Written to that path + +### Structure + +What the tables prove. Same answer every run. + +| File | Gap | Why | +| ----------- | ------- | ------------------------------------- | +| `.md` | missing | the capability always holds | +| `.md` | missing | `structure.md` scaffolds it | +| `.md` | orphan | no destination row produces it | + +### Findings + +What the reviewers saw this run. Another run may see more. + +| File | Finding | Evidence | +| ----------- | -------------------------------- | ----------------------------------- | +| `.md` | `` | `` | +| `.md` | names a path that does not exist | `` | + +### Duplicated facts + +| Fact | Home | Copy | +| --------- | ----------- | ----------- | +| `` | `.md` | `.md` | + +### Notes + +- `.md` — `` + +Notes hold what this run could not settle about the bank, and nothing else. Name a file, a +capability, a fact about the project. Never how this skill works, never one of its steps: the reader +wants their bank, not its machinery. + +- One row per file, per finding, per duplicated fact. Never a paragraph in a cell. +- A finding is a fragment; its evidence is the fact that settles it. +- Drop a table, a column, or a section that has nothing to say. diff --git a/aidd-context/skills/02-project-memory/assets/scan-summary.md b/aidd-context/skills/02-project-memory/assets/scan-summary.md new file mode 100644 index 000000000..669583a3d --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/scan-summary.md @@ -0,0 +1,23 @@ + + +Here is what I read. Correct me before I write. + +| Capability | Holds because | +| -------------- | ---------------------------------------------- | +| core | always | +| ecosystem | always | +| `` | `` | +| `` | `` | + +| Tool | Human | Agent | Owned by | +| ---------------- | -------- | -------- | ------------- | +| `` | `` | `` | `.md` | +| `` | `` | `` | `.md` | +| `` | `` | none | none | + +Then ask for what the repo cannot prove: a tool nobody committed, an access mode, a hand-off between +two tools. Name what is missing rather than asking an open question. + +- One row per capability, one row per tool. The evidence is a path or a dependency, never a claim. +- A capability that holds always says so; do not invent evidence for it. +- Drop the second table when the project reaches nothing outside itself. diff --git a/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md b/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md new file mode 100644 index 000000000..84d30658d --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md @@ -0,0 +1,45 @@ +# AGENTS.md + +> On 1st message, greet user with: "AI-Driven Development ON ⚡" + +## Behavior + +- **Stay critical.** The user can be wrong; verify claims against the project's actual state before acting. +- **Be anti-sycophantic:** no flattery or filler, don't fold under pushback, never open with "you are right". Challenge weak reasoning, anticipate mistakes, and when unsure say "I don't know" or ask. +- **Surface tradeoffs and evaluate their impact** instead of hiding them. + +## Communication + +- **Answer first:** result before reason. Drop pleasantries (sure, of course, happy to) and hedging. +- **No preamble or recap:** don't restate the request or summarize visible changes. Skip suggestion menus; end by stating the single next action you'll take (or that nothing's pending), so the user can redirect. +- **Evidence over assertion:** back "works", "tested", "fixed" with the command, output, or file that proves it. +- **Quote the shortest decisive line** of an error or log, not the whole dump. +- **No tool-call narration.** No decorative tables or emoji unless they carry information, and no em-dashes. +- **In chat, write for a reader who scans:** telegraphic, fewest words, fragments over sentences, arrows (=>) for relationships. Cut any word that doesn't change meaning. Normal prose in authored docs and code. Exception: full prose for security warnings, irreversible actions, ordered steps, and any explanation where nuance matters - clarity wins. + +## Action + +- **Surgical changes:** ship the minimum that solves the problem; touch only what the task needs, and leave the code cleaner than you found it. +- **Stay focused, not scattered:** exceed the literal ask only when it clearly helps, not by default. When you spot an unrelated issue, note it in one line and keep going; detour only if it blocks the task. +- **Solve your own issues first:** genuinely try to resolve it yourself before escalating to the human. +- **Do not commit or push** unless the user asks. +- **Don't assume your knowledge is current.** +- **Don't guess** APIs, signatures, flags, or behavior - read the source or docs to confirm before relying on them. +- **Ambiguous or expensive task:** ask one sharp question to pin down scope before building, rather than guess. +- **Batch independent operations** in one pass, not one at a time. +- **Fan out** independent subtasks to parallel subagents when you own the overall flow and the work is genuinely parallel. +- **Before adding any instruction, finding, or rule, check whether an existing one already covers or contradicts it.** If so, don't add a parallel: delete it, merge it into the stronger one, or rewrite with explicit scope and priority. +- **Name by intention, not mechanism:** describe the goal or responsibility, not the tool or file format. + +## Memory Management + +Project docs, memory, specs, and plans live in `aidd_docs/`. + +### Project memory + + + + +- If the block above is empty, run `ls -1tr aidd_docs/memory/` and read each file. +- Load `aidd_docs/memory/external/*` when the user asks. +- Load `aidd_docs/memory/internal/*` when the task needs it. diff --git a/aidd-context/skills/02-project-memory/assets/templates/CONTRIBUTING.md b/aidd-context/skills/02-project-memory/assets/templates/CONTRIBUTING.md new file mode 100644 index 000000000..0a44d5777 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Contributing to this project's AI context + +How to add or change the context the AI relies on here. Fill the placeholders below, drop what does not apply. For authoring AIDD skills, agents, rules, and templates, see the framework guide: . + +## Changing project memory + +Add or edit a file under `aidd_docs/memory/`. See [`memory/README.md`](memory/README.md) for what belongs there and how it loads. + +## Adding AI content (skills, rules, agents, commands, hooks) + +- Use the generator skills (`aidd-context:04-skill-generate` through `08-hook-generate`, and `10-learn` for memory or rules). They scaffold the right shape and write to the right place for each tool you use. +- Open a pull request for anything that changes how the AI behaves on this project. The team reviews it like any code change. + +## Adding recipes + +Create or edit project recipes under `aidd_docs/recipes/`. Use the cook skill when available so new recipes follow the shared contract and do not overwrite bundled framework recipes. + +## House conventions + +- +- diff --git a/aidd-context/skills/02-project-memory/assets/templates/GUIDELINES.md b/aidd-context/skills/02-project-memory/assets/templates/GUIDELINES.md new file mode 100644 index 000000000..5495c2bee --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/GUIDELINES.md @@ -0,0 +1,20 @@ +# AI Operating Guidelines + +How this team drives AI coding assistants on this project. Keep it short and specific to this repo. Fill the placeholders, drop what does not apply. + +## House rules + +- +- +- + +## Validation depth + +- +- + +## When the AI drifts + +- + +For the general AIDD playbook (planning, review loops, prompting and context hygiene, anti-patterns), see the framework docs: . diff --git a/aidd-context/skills/02-project-memory/assets/templates/README.md b/aidd-context/skills/02-project-memory/assets/templates/README.md new file mode 100644 index 000000000..4e053e830 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/README.md @@ -0,0 +1,17 @@ +# Project AI Docs + +Structured context the AI assistant reads to work on this project, so it does not rediscover the codebase each session. AIDD generates this folder and keeps it in sync. + +## What lives here + +- `memory/`: the project memory bank loaded each session. See [`memory/README.md`](memory/README.md). +- `recipes/`: project-specific how-to recipes created or updated by the cook skill. +- `GUIDELINES.md`: how this team operates the AI on this project. +- `CONTRIBUTING.md`: how to add or change project context. +- `tasks/`: specs, plans, and run summaries, created as work happens. + +The project memory block inside each AI context file (`CLAUDE.md`, `AGENTS.md`, and the rest) is generated and kept in sync, never edited by hand. To change what the AI sees, add or remove files under `memory/`. See [`memory/README.md`](memory/README.md) for the load tiers and the current file index. + +## The framework + +AIDD ships skills, agents, rules, and generators as a plugin marketplace. For the full catalog, the install guide, and the end-to-end workflow, see the framework docs: . diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/README.md b/aidd-context/skills/02-project-memory/assets/templates/memory/README.md new file mode 100644 index 000000000..11d30d42a --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/README.md @@ -0,0 +1,33 @@ +# memory/ - Project Memory + +Structured context the AI assistant reads at the start of a session, so it does not rediscover the project each time. + +## How it loads + +```mermaid +flowchart LR + bank["memory/*.md"] -->|every session| ai(["AI context"]) + notes["internal/ · external/"] -.->|on demand| ai +``` + +The root files load every session through the project memory block in each AI context file. `internal/` and `external/` load only when relevant. + +## Files + +Refreshed automatically by the memory hook. Do not edit by hand. + + + + +## Maintaining it + +The AI writes and refreshes these files. When you edit one by hand: + +- One file per concern (architecture, database, vcs, ...). +- Capture the macro and the non-derivable. Point to the code, never copy it. +- Current state only, kept small. No personal notes, no future TODOs. + +## Subdirectories + +- `internal/`: AIDD workflow traces (the capability profile, audit notes, learn captures). +- `external/`: external references the project pulls in (specs, design docs). diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md b/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md new file mode 100644 index 000000000..54935d4f1 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md @@ -0,0 +1,22 @@ +# API + +The HTTP API surface: its style, the main resources, and the contracts. + +## Style + +- +- + +## Resources + +- + +## Contracts + +- +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md b/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md new file mode 100644 index 000000000..63229f53e --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md @@ -0,0 +1,17 @@ +# Integration + +How this system integrates with external/third-party services. The map of every tool around the +project, this one included, lives in the ecosystem memory. + +## External services + +- + +## Calling conventions + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/auth/auth.md b/aidd-context/skills/02-project-memory/assets/templates/memory/auth/auth.md new file mode 100644 index 000000000..cf67fcdf9 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/auth/auth.md @@ -0,0 +1,26 @@ +# Auth + +How identity and access work: authentication and authorization. + +## Authentication + +- + +```mermaid +flowchart LR + TODO[client] -->|credentials| TODO2[provider] -->|token| TODO3[session] +``` + +## Authorization + +- + +## Sessions + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md b/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md new file mode 100644 index 000000000..8bdbb0836 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md @@ -0,0 +1,50 @@ +# Backlog + +## Supports + +| Support | Authority for | Role | +| --- | --- | --- | +| `` | `` | `` | + +## Structure + +```mermaid +flowchart TB + goal["Product goal"] --> epic["Epic"] + epic --> story["User Story"] + story --> task["Task"] + spike["Spike"] -. "resolves uncertainty for" .-> story + defect["Defect"] -. "affects" .-> story +``` + +## Representation + +| Artifact | Support | Native representation | +| --- | --- | --- | +| `` | `` | `` | + +## Workflow + +| Support | Native status | Meaning | +| --- | --- | --- | +| `` | `` | `` | + +## Planning + +- Priority: `` +- Estimation: `` +- Iteration: `` +- Milestone: `` + +## Relations + +- Parent: `` +- Dependency: `` +- Cross-support: `` + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/cli/cli.md b/aidd-context/skills/02-project-memory/assets/templates/memory/cli/cli.md new file mode 100644 index 000000000..d6b0b1b13 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/cli/cli.md @@ -0,0 +1,20 @@ +# CLI + +The command-line tool: its commands, inputs, and distribution. + +## Commands + +- + +## Interface + +- + +## Distribution + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md b/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md new file mode 100644 index 000000000..3d8443831 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md @@ -0,0 +1,32 @@ +# Architecture + +The macro technical shape: the stack, how the pieces fit, and the decisions behind them. Point to the code, do not restate it. + +## Stack + +- +- + +## How it fits together + +The macro flow between the main parts. One box per area, high level only. + +```mermaid +flowchart LR + A[TODO: replace with the real macro flow] +``` + +## Key decisions + +- +- + +## Gotchas + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/core/codebase-map.md b/aidd-context/skills/02-project-memory/assets/templates/memory/core/codebase-map.md new file mode 100644 index 000000000..b85e61597 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/core/codebase-map.md @@ -0,0 +1,27 @@ +# Codebase Map + +The macro layout: the top-level areas and what each holds. A map to navigate, not the full tree. + +```mermaid +flowchart TD + A[TODO: top-level areas, one box each, macro only] +``` + +## Areas + +- ``: +- ``: <...> + +## Entry points + +- + +## Packages + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/core/coding-assertions.md b/aidd-context/skills/02-project-memory/assets/templates/memory/core/coding-assertions.md new file mode 100644 index 000000000..d4afc7edc --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/core/coding-assertions.md @@ -0,0 +1,29 @@ +# Coding Assertions + +The checks that must pass for code to count as done. Minimal, run after every change. + +## Before commit + +The fast gate. + +| Order | Command | Checks | +| ----- | ----------- | ---------------- | +| 1 | `` | | + +## Before push + +The heavier gate. + +| Order | Command | Checks | +| ----- | ----------- | ------------------- | +| 1 | `` | | + +## Behavior + +I fix is needed, spawn 1 agent per assertion to fix (e.g typechecking / tests / rules violated on category UI = 3 agents). + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/core/project-brief.md b/aidd-context/skills/02-project-memory/assets/templates/memory/core/project-brief.md new file mode 100644 index 000000000..eaed13293 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/core/project-brief.md @@ -0,0 +1,29 @@ +# Project Brief + +What this project is, the problem it solves, and its domain language. The non-derivable "why", not the "how". + +## What it is + +- + +## Why it exists + +- + +## Domain language + +The terms a contributor must know to read the code. + +| Term | Meaning | +| ---- | ------- | +| | | + +## Key features + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md b/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md new file mode 100644 index 000000000..bd6dc76e5 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md @@ -0,0 +1,31 @@ +# Testing + +How the project is tested: the layers, the tools, and the conventions. Where tests live and how to run them. + +## Strategy + +- + +## Tools + +- + +## Conventions + +- + +## Run + +- + +## Browser QA + +- Entry: +- Auth: +- State: + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md b/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md new file mode 100644 index 000000000..67413f33d --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md @@ -0,0 +1,29 @@ +# VCS + +The version-control conventions this project follows: branches, commits, and the platform. + +## Setup + +- Main branch: `` +- Platform: `` + +## Branches + +- Format: `` +- Types in use: `` + +## Commits + +- Convention: `` +- Format: `` +- Rules: `` + +## Commit Strategy + +AI should auto commit: `never|after phase|after feature|after task done|post-tests` + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/data/data.md b/aidd-context/skills/02-project-memory/assets/templates/memory/data/data.md new file mode 100644 index 000000000..cbca9ea12 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/data/data.md @@ -0,0 +1,29 @@ +# Data + +The data and ML side: sources, pipelines, and models. + +## Sources + +- + +## Pipeline + +The processing stages from raw to output. + +```mermaid +flowchart LR + Source --> Process[TODO] --> Output +``` + +## Models + +- + +## Reproducibility + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md b/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md new file mode 100644 index 000000000..1e80c7e87 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md @@ -0,0 +1,27 @@ +# Database + +The data store: its type, the main entities, and the conventions. The macro model, not the full schema. + +## Setup + +- + +## Main entities + +The aggregate roots and how the main entities group: the design the schema does not show. Point to the schema file for columns and keys. + +```mermaid +flowchart LR + TODO[aggregate root] --> TODO2[owned entity] +``` + +## Conventions + +- +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md b/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md new file mode 100644 index 000000000..ec2a92eae --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md @@ -0,0 +1,31 @@ +# Deployment + +Where the project runs and how it ships: CI/CD, environments, and release. + +## Pipeline + +- +- + +```mermaid +flowchart LR + TODO[push] --> TODO2[build] --> TODO3[test] --> TODO4[deploy] +``` + +## Environments + +- + +## Release + +- + +## Monitoring + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/desktop/desktop.md b/aidd-context/skills/02-project-memory/assets/templates/memory/desktop/desktop.md new file mode 100644 index 000000000..73caa0e08 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/desktop/desktop.md @@ -0,0 +1,20 @@ +# Desktop + +The desktop app: framework, native access, and packaging. + +## Framework + +- + +## Native access + +- + +## Build and release + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md b/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md new file mode 100644 index 000000000..57a002c5d --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md @@ -0,0 +1,32 @@ +# Ecosystem + +```mermaid +flowchart LR + Human([Human]) + Agent([Agent]) + App([App]) + Vcs[" · vcs.md"] + Tracker[" · backlog.md"] + Service[" · integration.md"] + Chat[" · human only"] + Bot[""] + + Agent -- cli --> Vcs + Agent -- mcp --> Tracker + App -- http --> Service + Human -- web --> Chat + + Vcs -- "" --> Tracker + Bot -- "" --> Vcs +``` + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/infra/infra.md b/aidd-context/skills/02-project-memory/assets/templates/memory/infra/infra.md new file mode 100644 index 000000000..4e9861b10 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/infra/infra.md @@ -0,0 +1,25 @@ +# Infrastructure + +How the runtime is provisioned: infrastructure as code and topology. + +## Tooling + +- + +## Topology + +The main resources (compute, network, storage) and how they connect. + +```mermaid +flowchart TD + A[TODO: macro infrastructure topology] +``` + +## Conventions + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/messaging/messaging.md b/aidd-context/skills/02-project-memory/assets/templates/memory/messaging/messaging.md new file mode 100644 index 000000000..db5e1a29c --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/messaging/messaging.md @@ -0,0 +1,25 @@ +# Messaging + +How the system handles asynchronous work: queues and events. + +## Broker + +- + +## Topics + +- + +## Conventions + +- + +```mermaid +flowchart LR + Producer --> Queue[Queue: TODO] --> Consumer +``` + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/mobile/mobile.md b/aidd-context/skills/02-project-memory/assets/templates/memory/mobile/mobile.md new file mode 100644 index 000000000..7f15ab77f --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/mobile/mobile.md @@ -0,0 +1,33 @@ +# Mobile + +The mobile app: platform, navigation, native access, and release. + +## Platform + +- + +## Navigation + +The macro screen flow. + +```mermaid +flowchart LR + A[TODO: macro screen flow] +``` + +## Native access + +- + +## State and storage + +- + +## Build and release + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/package/package.md b/aidd-context/skills/02-project-memory/assets/templates/memory/package/package.md new file mode 100644 index 000000000..230f352ff --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/package/package.md @@ -0,0 +1,21 @@ +# Package + +What this project ships as a reusable package: its public surface and release policy. + +## Public API + +- + +## Consumers + +- + +## Versioning + +- +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/realtime/realtime.md b/aidd-context/skills/02-project-memory/assets/templates/memory/realtime/realtime.md new file mode 100644 index 000000000..95f11e4d8 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/realtime/realtime.md @@ -0,0 +1,25 @@ +# Realtime + +How the project pushes live updates: the transport and the channels. + +## Transport + +- + +## Channels + +- + +## Conventions + +- + +```mermaid +flowchart LR + Client --> Server --> Client2[Client] +``` + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md b/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md new file mode 100644 index 000000000..9c18e9dd9 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md @@ -0,0 +1,25 @@ +# Design + +The visual language: the design system, tokens, and UI conventions. What it looks like, not how it is coded. + +## System + +- +- + +## Tokens + +- + +## Components + +- + +## Accessibility + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/ui/forms.md b/aidd-context/skills/02-project-memory/assets/templates/memory/ui/forms.md new file mode 100644 index 000000000..17eef60e2 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/ui/forms.md @@ -0,0 +1,17 @@ +# Forms + +How forms are built and validated across the UI. + +## Approach + +-
+- + +## Conventions + +- + + diff --git a/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md b/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md new file mode 100644 index 000000000..8787d1e70 --- /dev/null +++ b/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md @@ -0,0 +1,22 @@ +# Navigation + +How the user moves through the app: routing and the page structure. + +## Routing + +- +- + +## Structure + +The macro page map, main sections only. + +```mermaid +flowchart LR + A[TODO: main sections] +``` + + diff --git a/aidd-context/skills/02-project-memory/references/capability-signals.md b/aidd-context/skills/02-project-memory/references/capability-signals.md new file mode 100644 index 000000000..47b2d05c9 --- /dev/null +++ b/aidd-context/skills/02-project-memory/references/capability-signals.md @@ -0,0 +1,24 @@ +# Capability signals + +A concern scan detects from a concrete fact in the repo, or an equivalent one, never inferred from the domain. + +In a monorepo, every workspace is scanned, never the root manifest alone. + +| Capability | Means | Detected when | +| ------------ | ------------------------------ | ----------------------------------------------------------------------------------------- | +| `core` | is a project at all | always | +| `ecosystem` | works through external tools | always | +| `backlog` | organizes planned work | local backlog artifacts, issue templates, a ticketing tool in use, or a repo file naming backlog conventions | +| `ui` | renders a user interface | a web frontend framework (not React Native), or a `components/`, `pages/`, or `views/` dir | +| `api` | exposes HTTP or RPC | a server framework, or a `routes/`, `controllers/`, or `api/` dir | +| `database` | persists data | an ORM or driver, a `migrations/` dir, or a schema file | +| `auth` | authenticates or authorizes | an auth library (passport, next-auth, clerk, auth0, devise), auth middleware, or an auth module | +| `realtime` | pushes live updates | a websocket or SSE library (socket.io, ws, pusher, ably, channels, actioncable), or a socket endpoint | +| `messaging` | async messages | a queue or broker (kafka, rabbitmq, sqs, bullmq) with producers or consumers | +| `deployment` | is built and shipped | a CI config, or a `Dockerfile` | +| `infra` | infrastructure as code | Terraform, Pulumi, Kubernetes, or Helm files | +| `mobile` | ships a mobile app | an `ios/` or `android/` dir, a `pubspec.yaml`, a `Podfile`, or React Native or Flutter | +| `desktop` | ships a desktop app | Electron, Tauri, or a native desktop toolkit (Qt, GTK, WPF, AppKit) | +| `package` | ships a reusable library | a publishable manifest declaring an importable entry that is not the CLI bin (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`) | +| `cli` | runs as a command-line tool | a `bin` field, or a CLI parser (commander, yargs, oclif, clap, click) | +| `data` | processes data or trains models | notebooks, a data-versioning or ML tool, or pipeline and model files | diff --git a/aidd-context/skills/02-project-memory/references/ecosystem-signals.md b/aidd-context/skills/02-project-memory/references/ecosystem-signals.md new file mode 100644 index 000000000..4bc0445b4 --- /dev/null +++ b/aidd-context/skills/02-project-memory/references/ecosystem-signals.md @@ -0,0 +1,47 @@ +# Ecosystem signals + +What the scan learns about the services the project uses and does not build. The AI hosts it wires +the memory into are `tools.md`, not this. + +## What earns an entry + +- It holds state, or does work, outside the repo past a single CI run. A build step does not. +- One entry per role: a platform that is also the tracker gives two. +- The VCS platform always counts: a repo has one, so the graph is never empty. + +## Actors + +| Actor | Is | +| ------- | ------------------------- | +| `Human` | a person opening the tool | +| `Agent` | an AI assistant driving it | +| `App` | the running code calling it | + +## Access modes + +| Mode | Means | +| ------ | --------------------------------------- | +| `mcp` | an MCP server the agent calls | +| `cli` | a command run in a terminal | +| `http` | a direct API call | +| `web` | a browser interface, nothing programmatic | + +## What earns an edge + +| Edge | Verdict | +| --------------------------------- | ---------------------------------------------------------- | +| `Agent` reaching a tool | keep, what an assistant can drive is never obvious | +| `App` reaching a tool | keep, it names a runtime dependency | +| `Human` reaching a tool by `web` | drop, a person opens anything in a browser | +| `Human` where no agent can follow | keep as `human only` in the label, so absence is not doubt | +| a hand-off with its trigger | keep, the trigger is what makes it a rule | +| a tool nobody drives | keep it for its hand-off alone: acting on its own is the fact | +| a hand-off without one | keep the edge, name the trigger the repo proves | + +## Detected when + +| Fact | Read as | +| -------------------------------------------------------------------- | ------------------------------------------ | +| a service config or a repo integration, whoever runs it, plus a badge | the tool exists | +| a CI config, a webhook, or an integration naming two tools | a hand-off between them | +| the user names it | what the repo cannot prove | diff --git a/aidd-context/skills/02-project-memory/references/memory-destinations.md b/aidd-context/skills/02-project-memory/references/memory-destinations.md new file mode 100644 index 000000000..dbffcffbc --- /dev/null +++ b/aidd-context/skills/02-project-memory/references/memory-destinations.md @@ -0,0 +1,36 @@ +# Memory destinations + +Where each template under `assets/templates/` lands. Read from this table, never derived. + +Read backwards, it names the capabilities a bank already holds: a file present means its row's capability held when the bank was written. + +| Capability | Template | Write to | +| ---------- | ---------------------------------- | --------------------------------------- | +| core | `README.md` | `aidd_docs/README.md` | +| core | `GUIDELINES.md` | `aidd_docs/GUIDELINES.md` | +| core | `CONTRIBUTING.md` | `aidd_docs/CONTRIBUTING.md` | +| core | `memory/README.md` | `aidd_docs/memory/README.md` | +| core | `memory/core/project-brief.md` | `aidd_docs/memory/project-brief.md` | +| core | `memory/core/architecture.md` | `aidd_docs/memory/architecture.md` | +| core | `memory/core/codebase-map.md` | `aidd_docs/memory/codebase-map.md` | +| core | `memory/core/coding-assertions.md` | `aidd_docs/memory/coding-assertions.md` | +| core | `memory/core/testing.md` | `aidd_docs/memory/testing.md` | +| core | `memory/core/vcs.md` | `aidd_docs/memory/vcs.md` | +| ecosystem | `memory/ecosystem/ecosystem.md` | `aidd_docs/memory/ecosystem.md` | +| backlog | `memory/backlog/backlog.md` | `aidd_docs/memory/backlog.md` | +| api | `memory/api/api.md` | `aidd_docs/memory/api.md` | +| api | `memory/api/integration.md` | `aidd_docs/memory/integration.md` | +| auth | `memory/auth/auth.md` | `aidd_docs/memory/auth.md` | +| cli | `memory/cli/cli.md` | `aidd_docs/memory/cli.md` | +| data | `memory/data/data.md` | `aidd_docs/memory/data.md` | +| database | `memory/database/database.md` | `aidd_docs/memory/database.md` | +| deployment | `memory/deployment/deployment.md` | `aidd_docs/memory/deployment.md` | +| desktop | `memory/desktop/desktop.md` | `aidd_docs/memory/desktop.md` | +| infra | `memory/infra/infra.md` | `aidd_docs/memory/infra.md` | +| messaging | `memory/messaging/messaging.md` | `aidd_docs/memory/messaging.md` | +| mobile | `memory/mobile/mobile.md` | `aidd_docs/memory/mobile.md` | +| package | `memory/package/package.md` | `aidd_docs/memory/package.md` | +| realtime | `memory/realtime/realtime.md` | `aidd_docs/memory/realtime.md` | +| ui | `memory/ui/design.md` | `aidd_docs/memory/design.md` | +| ui | `memory/ui/forms.md` | `aidd_docs/memory/forms.md` | +| ui | `memory/ui/navigation.md` | `aidd_docs/memory/navigation.md` | diff --git a/aidd-context/skills/02-project-memory/references/memory-rules.md b/aidd-context/skills/02-project-memory/references/memory-rules.md new file mode 100644 index 000000000..fa434fcdf --- /dev/null +++ b/aidd-context/skills/02-project-memory/references/memory-rules.md @@ -0,0 +1,13 @@ +# Memory rules + +A memory file: + +- Captures the macro and the non-derivable: decisions, conventions, gotchas, the why. +- Never restates a schema or a file tree. +- Points to the code over a copy. +- Holds one fact in one home, referenced elsewhere. +- A duplicate keeps its home and loses the copy. +- Stays small: short bullets, code in backticks. +- Names a tech without its version (`React`, not `React 19`). +- Reflects the current state only: no unused section, no placeholder. +- Carries the diagram alone when a diagram is its payload: no note, no caption under it. diff --git a/aidd-context/skills/02-project-memory/references/reading-sources.md b/aidd-context/skills/02-project-memory/references/reading-sources.md new file mode 100644 index 000000000..dbc39a760 --- /dev/null +++ b/aidd-context/skills/02-project-memory/references/reading-sources.md @@ -0,0 +1,45 @@ +# Reading sources + +What the scan reads to understand the project, and what survives the reading. Read widely, keep +little: `memory-rules.md` wants a small file, and most of what a repository shows is re-derivable by +opening it again. + +## Read in this order + +| Source | Answers | +| -------------------------------------------- | -------------------------------------------- | +| the manifest, and a lockfile beside it | the stack, the workspaces, the published name | +| the root README, then any `docs/` | what it does, for whom, its domain words | +| the top-level directories | the shape, and which areas own what | +| the entry points the manifest declares | where execution starts | +| every file under the VCS platform's own directory | how it ships, and what runs on its own schedule | +| the test configuration and one test file | the layers, the tools, the conventions | +| the code, area by area | what the writing above got wrong | + +Stop at the first source that answers a question. Read the code last: it is the most expensive and +the least quotable, and it exists to correct the others, not to be summarised. + +## Keep or drop + +This table judges what the reading yields, never what a memory file already holds. A line the user +wrote stays whatever the verdicts below say. + +| Signal | Verdict | +| ------------------------------------------------------------- | ------- | +| a decision, and the constraint behind it | keep | +| a convention the files repeat without stating | keep | +| a gotcha, a trap, a thing that surprises a newcomer | keep | +| the stack, and how the main parts fit | keep | +| the domain words a contributor must know to read the code | keep | +| a fact one open file re-derives | drop | +| a file tree, a schema, a dependency list | drop | +| a version number | drop | +| anything true of every project built this way | drop | +| a work item, a live value, a technical id | drop | +| a plan, a wish, a thing not shipped | drop | + +## Depth + +- Every workspace of a monorepo, never the root manifest alone. +- A directory whose name repeats across areas is read once, not per area. +- Nothing under a dependency directory, a build output, or a path the VCS ignores. diff --git a/aidd-context/skills/02-project-memory/references/review-protocol.md b/aidd-context/skills/02-project-memory/references/review-protocol.md new file mode 100644 index 000000000..7d1d53090 --- /dev/null +++ b/aidd-context/skills/02-project-memory/references/review-protocol.md @@ -0,0 +1,16 @@ +# Review protocol + +You review one memory file the AI loads every session. Catch what its writer could not see. + +Memory holds what the code cannot show: an intent, a constraint, a warning. Code silent on a line is +not code that contradicts it. + +1. **Read** the file, the code it describes, and the other memory files' names. +2. **Flag** each of these, with a reason and a location: + - A claim the code contradicts, or that has gone stale. + - A command, path, or file that does not exist or would not run. + - A "why" the code and history do not support. + - A decision, convention, or gotcha the code shows but the file omits. + - A fact that belongs under another file's name, for check to dedup. + - Any remaining breach of `memory-rules.md`. +3. **Return** the flags. Do not edit the file. diff --git a/aidd-context/skills/02-project-memory/references/structure.md b/aidd-context/skills/02-project-memory/references/structure.md new file mode 100644 index 000000000..ced17dcff --- /dev/null +++ b/aidd-context/skills/02-project-memory/references/structure.md @@ -0,0 +1,20 @@ +# Structure + +The tree write scaffolds. Which template fills which file is `memory-destinations.md`; this is the +shape around them, and who owns each part. + +```txt +aidd_docs/ +├── README.md copied as is +├── GUIDELINES.md the team fills its placeholders +├── CONTRIBUTING.md the team fills its placeholders +└── memory/ + ├── README.md copied as is, its file list refreshed by the hook + ├── .md the AI writes these, flat, never nested + ├── internal/ a .gitkeep, internal notes read on demand + └── external/ a .gitkeep, external notes read on demand +``` + +- The three root docs are the team's. Their placeholders survive until a human answers them. +- Everything under `memory/` is the AI's, and sits at its root. +- `internal/` and `external/` exist even when empty. diff --git a/aidd-context/skills/02-project-memory/references/tools.md b/aidd-context/skills/02-project-memory/references/tools.md new file mode 100644 index 000000000..4b90d76d1 --- /dev/null +++ b/aidd-context/skills/02-project-memory/references/tools.md @@ -0,0 +1,17 @@ +# Tools + +The AI tools a project can use. + +| Tool | Detected when | Context file | +| -------- | ------------------------------------------------------------------------------------ | --------------------------------- | +| claude | `.claude/` or `CLAUDE.md` | `CLAUDE.md` | +| codex | `.codex/` | `AGENTS.md` | +| cursor | `.cursor/` or `.cursorrules` | `AGENTS.md` | +| opencode | `.opencode/` | `AGENTS.md` | +| copilot | `.github/copilot-instructions.md` or `.github/{instructions,agents,skills,prompts}/` | `.github/copilot-instructions.md` | + +- A shared `AGENTS.md` is a wiring target, never a detection signal. +- Tools sharing a context file wire it once; the block serves them all. +- A context file carries the block under a `## Memory Management` section, shaped like `assets/templates/AGENTS.md`. +- An existing context file keeps everything else: add only what is missing. +- Touch no context file a picked tool does not resolve to. diff --git a/aidd-context/skills/03-context-generate/SKILL.md b/aidd-context/skills/03-context-generate/SKILL.md new file mode 100644 index 000000000..6040a4dfa --- /dev/null +++ b/aidd-context/skills/03-context-generate/SKILL.md @@ -0,0 +1,21 @@ +--- +name: 03-context-generate +description: Route a request to generate a context artifact (skill, rule, agent, command, or hook) to its generator when the kind is unnamed. A named kind triggers its generator directly. Not for listing existing artifacts. +argument-hint: skill | rule | agent | command | hook +--- + +# Context Generate + +Routes a generation request to the dedicated generator for the artifact kind. Holds no generation logic of its own. + +## Routing + +| Artifact | Generator | +| -------- | -------------------------------- | +| skill | `aidd-context:04-skill-generate` | +| rule | `aidd-context:05-rule-generate` | +| agent | `aidd-context:06-agent-generate` | +| command | `aidd-context:07-command-generate` | +| hook | `aidd-context:08-hook-generate` | + +Identify the artifact kind from the request, then hand off to the matching generator. If the kind is unclear, ask which one. To survey or list existing artifacts, use the explore skill instead. diff --git a/aidd-context/skills/04-skill-generate/SKILL.md b/aidd-context/skills/04-skill-generate/SKILL.md new file mode 100644 index 000000000..6e546fb72 --- /dev/null +++ b/aidd-context/skills/04-skill-generate/SKILL.md @@ -0,0 +1,31 @@ +--- +name: 04-skill-generate +description: Generate a router-based skill across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a skill, or turn a workflow into one. Not for other artifacts like rules, agents, commands, hooks. +argument-hint: create | modify +--- + +# Skill Generate + +```mermaid +flowchart LR + new([create]) --> scope --> plan --> write --> validate + edit([modify]) --> plan +``` + +## Actions + +Run the flow above. Read only the next action file. + +| Action | Does | +| -------- | -------------------------- | +| scope | frame the skill and target | +| plan | break it into actions | +| write | write the router and files | +| validate | review the files and fix | + +## Transversal rules + +- Default to `create`; follow `modify` when asked. +- If a cited reference cannot be read, stop and report the missing file. +- Confirm every target and name with the user. +- Never write silently. diff --git a/aidd-context/skills/04-skill-generate/actions/01-scope.md b/aidd-context/skills/04-skill-generate/actions/01-scope.md new file mode 100644 index 000000000..2ed28f681 --- /dev/null +++ b/aidd-context/skills/04-skill-generate/actions/01-scope.md @@ -0,0 +1,28 @@ +# 01 - Scope + +Frame the skill before any file is touched. + +## Input + +A free-form request to create a skill. + +## Output + +The confirmed frame, written nowhere, per [scope-frame.md](../references/scope-frame.md). + +## Process + +1. **Detect.** Detect the installed tools per [tool-detect.md](../references/tool-detect.md). +2. **Fill.** For each field in [scope-frame.md](../references/scope-frame.md), propose a value or ask one question. +3. **Check.** Check the name per [naming.md](../references/naming.md) and surface any overlap. +4. **Confirm.** Hand the confirmed frame to plan. + +## Test + +| Case | Pass | +| --- | --- | +| The action runs to completion | `git status --porcelain` reads the same after as before | +| A name overlaps an installed skill | the overlap is surfaced before the frame is handed on | +| No name overlaps | the run states that it found none | +| A frame field needs the user | one question is asked, and only that one | +| The frame is handed to plan | its target was confirmed by the user first | diff --git a/aidd-context/skills/04-skill-generate/actions/02-plan.md b/aidd-context/skills/04-skill-generate/actions/02-plan.md new file mode 100644 index 000000000..41c70fa72 --- /dev/null +++ b/aidd-context/skills/04-skill-generate/actions/02-plan.md @@ -0,0 +1,27 @@ +# 02 - Plan + +Break the skill into atomic, testable actions: one action, one job. + +## Input + +- From scope, the create frame. +- For a modify, the existing skill, read in place. + +## Output + +A plan table, one row per action: slug, input to output, test, and any dependency. + +## Process + +1. **List.** List every distinct job the output needs. Modify: start from the existing actions, touch only the jobs the user named. +2. **Atomize.** Prefer few actions, a job each, not a step. Merge two that share most logic. +3. **Number.** Name, number, and give each an observable test, per [skill-authoring.md](../references/skill-authoring.md). +4. **Confirm.** Present the table, validate each test with the user. + +## Test + +| Case | Pass | +| --- | --- | +| The table is presented | every row is one job carrying a checkable test | +| A row consumes an output | that output comes from an earlier row, never a later one | +| The run is a modify | only the jobs the user named have a row | diff --git a/aidd-context/skills/04-skill-generate/actions/03-write.md b/aidd-context/skills/04-skill-generate/actions/03-write.md new file mode 100644 index 000000000..595826e48 --- /dev/null +++ b/aidd-context/skills/04-skill-generate/actions/03-write.md @@ -0,0 +1,34 @@ +# 03 - Write + +Write the skill tree from the plan. + +## Input + +- The plan from 02. +- The target from 01, or for a modify the existing skill's own location. + +## Output + +The skill tree at the target, and the list of files written. + +## Process + +1. **Tree.** Create the shape in [skill-tree.md](../references/skill-tree.md). +2. **Router.** Fill [skill-template.md](../assets/skill-template.md) against [skill-authoring.md](../references/skill-authoring.md), strip the scaffold. + - Modify: revise the existing SKILL.md in place, keeping the user's edits. +3. **Actions.** Fill [action-template.md](../assets/action-template.md) per row against [skill-authoring.md](../references/skill-authoring.md), its test copied from the plan. + - Modify: revise a changed action in place. Leave an untouched one alone. +4. **Hint.** Set `argument-hint` per [skill-authoring.md](../references/skill-authoring.md). +5. **Place.** Write once per confirmed target, using [tool-write.md](../references/tool-write.md). +6. **Check.** Confirm every written path is relative, inside the workspace, outside the plugin install directory, and under the chosen target. Else stop and report it. + +## Test + +| Case | Pass | +| --- | --- | +| The router is written | it holds a `mermaid` flowchart and an `Action \| Does` table | +| The action table is read back | every slug is bare and every `Does` is a lowercase imperative with no final period | +| An action file is written | it holds `## Output`, `## Process`, and a `Case \| Pass` `## Test` | +| The tree is written | its shape matches [skill-tree.md](../references/skill-tree.md) | +| Any written file is read back | no `<` placeholder and no template instruction line survives | +| A path resolves outside the chosen target | the run stops and reports that path | diff --git a/aidd-context/skills/04-skill-generate/actions/04-validate.md b/aidd-context/skills/04-skill-generate/actions/04-validate.md new file mode 100644 index 000000000..fca3dacbb --- /dev/null +++ b/aidd-context/skills/04-skill-generate/actions/04-validate.md @@ -0,0 +1,25 @@ +# 04 - Validate + +Review the written skill against the contract and fix what breaks. + +## Input + +The skill written by 03. + +## Output + +A report, one row per file: what was checked and any fix applied. + +## Process + +1. **Review.** Review each file against [review-protocol.md](../references/review-protocol.md). +2. **Fix.** Apply the confirmed fixes on disk, then re-review the changed files. +3. **Report.** Deliver the findings, even when clean. + +## Test + +| Case | Pass | +| --- | --- | +| The report is delivered | every written file has a row, with its findings or none | +| The review finds a breach | it names the broken rule and a `file:line` | +| A fix is confirmed | the file differs on disk and is reviewed again | diff --git a/aidd-context/skills/04-skill-generate/assets/action-template.md b/aidd-context/skills/04-skill-generate/assets/action-template.md new file mode 100644 index 000000000..be7d9cc99 --- /dev/null +++ b/aidd-context/skills/04-skill-generate/assets/action-template.md @@ -0,0 +1,24 @@ +# + + + +## Input + + + +## Output + + + +## Process + +1. **