@llipe.com/dev-tasks 0.10.0 → 0.16.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents/developer.md +108 -35
- package/.claude/agents/github-ops.md +48 -4
- package/.claude/agents/housekeeping.md +44 -7
- package/.claude/agents/qa-engineer.md +45 -3
- package/.claude/agents/researcher.md +116 -0
- package/.claude/agents/technical-writer.md +61 -6
- package/.claude/agents/ux-engineer.md +1 -0
- package/.claude/agents/verifier.md +48 -6
- package/.claude/commands/developer.md +2 -266
- package/.claude/commands/infra-engineer.md +92 -0
- package/.claude/commands/planner.md +64 -28
- package/.claude/commands/product-engineer.md +58 -19
- package/.claude/commands/researcher.md +27 -0
- package/.claude/commands/technical-writer.md +1 -1
- package/.claude/hooks/branch-guard.sh +30 -0
- package/.claude/hooks/git-guard.sh +483 -22
- package/.claude/skills/activity-codebase-research/SKILL.md +151 -0
- package/.claude/skills/activity-e2e-test-implementation/SKILL.md +156 -0
- package/.claude/skills/activity-generate-spec/SKILL.md +34 -10
- package/.claude/skills/activity-grill/SKILL.md +150 -0
- package/.claude/skills/activity-init/SKILL.md +121 -71
- package/.claude/skills/activity-integration-test-implementation/SKILL.md +156 -0
- package/.claude/skills/activity-refine/SKILL.md +75 -15
- package/.claude/skills/activity-test-standards/SKILL.md +66 -0
- package/.claude/skills/aws-ops/SKILL.md +155 -0
- package/.claude/skills/deploy-ops/SKILL.md +121 -0
- package/.claude/skills/fly-ops/SKILL.md +138 -0
- package/.claude/skills/git-ops/SKILL.md +27 -7
- package/.claude/skills/implement/SKILL.md +49 -4
- package/.claude/skills/memo-cli-usage/REFERENCE.md +230 -17
- package/.claude/skills/memo-cli-usage/SKILL.md +66 -13
- package/.claude/skills/plan/SKILL.md +43 -1
- package/.claude/skills/supabase-ops/SKILL.md +109 -0
- package/.github/agents/developer.agent.md +80 -18
- package/.github/agents/github-ops.agent.md +46 -4
- package/.github/agents/housekeeping.agent.md +43 -7
- package/.github/agents/infra-engineer.agent.md +139 -0
- package/.github/agents/planner.agent.md +45 -9
- package/.github/agents/product-engineer.agent.md +58 -19
- package/.github/agents/qa-engineer.agent.md +43 -4
- package/.github/agents/researcher.agent.md +115 -0
- package/.github/agents/technical-writer.agent.md +60 -6
- package/.github/agents/verifier.agent.md +46 -5
- package/.github/instructions/implement.instructions.md +49 -4
- package/.github/instructions/plan.instructions.md +43 -1
- package/.github/prompts/infra-engineer.prompt.md +12 -0
- package/.github/prompts/product-engineer-init.prompt.md +5 -6
- package/.github/prompts/researcher.prompt.md +28 -0
- package/.github/prompts/technical-writer.prompt.md +1 -1
- package/.github/skills/activity-codebase-research/SKILL.md +146 -0
- package/.github/skills/activity-e2e-test-implementation/SKILL.md +156 -0
- package/.github/skills/activity-generate-spec/SKILL.md +34 -10
- package/.github/skills/activity-grill/SKILL.md +145 -0
- package/.github/skills/activity-init/SKILL.md +120 -70
- package/.github/skills/activity-integration-test-implementation/SKILL.md +156 -0
- package/.github/skills/activity-refine/SKILL.md +75 -15
- package/.github/skills/activity-test-standards/SKILL.md +66 -0
- package/.github/skills/aws-ops/SKILL.md +150 -0
- package/.github/skills/deploy-ops/SKILL.md +116 -0
- package/.github/skills/fly-ops/SKILL.md +133 -0
- package/.github/skills/git-ops/SKILL.md +27 -7
- package/.github/skills/memo-cli-usage/REFERENCE.md +230 -17
- package/.github/skills/memo-cli-usage/SKILL.md +66 -13
- package/.github/skills/supabase-ops/SKILL.md +104 -0
- package/.kiro/agents/developer.md +81 -19
- package/.kiro/agents/github-ops.md +46 -4
- package/.kiro/agents/housekeeping.md +44 -8
- package/.kiro/agents/infra-engineer.md +102 -0
- package/.kiro/agents/planner.md +53 -20
- package/.kiro/agents/product-engineer.md +61 -22
- package/.kiro/agents/qa-engineer.md +44 -5
- package/.kiro/agents/researcher.md +118 -0
- package/.kiro/agents/technical-writer.md +63 -9
- package/.kiro/agents/verifier.md +48 -7
- package/.kiro/skills/activity-codebase-research/SKILL.md +151 -0
- package/.kiro/skills/activity-e2e-test-implementation/SKILL.md +156 -0
- package/.kiro/skills/activity-generate-spec/SKILL.md +34 -10
- package/.kiro/skills/activity-grill/SKILL.md +150 -0
- package/.kiro/skills/activity-init/SKILL.md +121 -71
- package/.kiro/skills/activity-integration-test-implementation/SKILL.md +156 -0
- package/.kiro/skills/activity-refine/SKILL.md +75 -15
- package/.kiro/skills/activity-test-standards/SKILL.md +66 -0
- package/.kiro/skills/aws-ops/SKILL.md +155 -0
- package/.kiro/skills/deploy-ops/SKILL.md +121 -0
- package/.kiro/skills/fly-ops/SKILL.md +138 -0
- package/.kiro/skills/git-ops/SKILL.md +27 -7
- package/.kiro/skills/memo-cli-usage/REFERENCE.md +230 -17
- package/.kiro/skills/memo-cli-usage/SKILL.md +66 -13
- package/.kiro/skills/supabase-ops/SKILL.md +109 -0
- package/.kiro/steering/implement.md +49 -4
- package/.kiro/steering/plan.md +43 -1
- package/AGENTS.md +88 -261
- package/AGENTS.md.template +124 -0
- package/CHANGELOG.md +196 -0
- package/CLAUDE.md +24 -18
- package/CLAUDE.md.template +103 -0
- package/README.md +168 -145
- package/TESTING.md +84 -140
- package/bundle-manifest.json +43 -2
- package/dist/bin/dev-tasks.js +65 -3
- package/dist/bin/dev-tasks.js.map +1 -1
- package/dist/{adapters/cli → bin}/parse-args.d.ts +2 -6
- package/dist/bin/parse-args.d.ts.map +1 -0
- package/dist/{adapters/cli → bin}/parse-args.js +2 -18
- package/dist/bin/parse-args.js.map +1 -0
- package/dist/core/checks/decision-log-format.d.ts +44 -0
- package/dist/core/checks/decision-log-format.d.ts.map +1 -0
- package/dist/core/checks/decision-log-format.js +171 -0
- package/dist/core/checks/decision-log-format.js.map +1 -0
- package/dist/core/checks/docs-structure.d.ts +82 -0
- package/dist/core/checks/docs-structure.d.ts.map +1 -0
- package/dist/core/checks/docs-structure.js +285 -0
- package/dist/core/checks/docs-structure.js.map +1 -0
- package/dist/core/checks/glossary.d.ts +178 -0
- package/dist/core/checks/glossary.d.ts.map +1 -0
- package/dist/core/checks/glossary.js +651 -0
- package/dist/core/checks/glossary.js.map +1 -0
- package/dist/core/checks/index.d.ts +19 -0
- package/dist/core/checks/index.d.ts.map +1 -0
- package/dist/core/checks/index.js +16 -0
- package/dist/core/checks/index.js.map +1 -0
- package/dist/core/checks/run.d.ts +22 -0
- package/dist/core/checks/run.d.ts.map +1 -0
- package/dist/core/checks/run.js +51 -0
- package/dist/core/checks/run.js.map +1 -0
- package/dist/core/distribution/doctor.d.ts +46 -1
- package/dist/core/distribution/doctor.d.ts.map +1 -1
- package/dist/core/distribution/doctor.js +161 -2
- package/dist/core/distribution/doctor.js.map +1 -1
- package/dist/core/distribution/index.d.ts +9 -3
- package/dist/core/distribution/index.d.ts.map +1 -1
- package/dist/core/distribution/index.js +5 -2
- package/dist/core/distribution/index.js.map +1 -1
- package/dist/core/distribution/install-if-absent.d.ts +46 -0
- package/dist/core/distribution/install-if-absent.d.ts.map +1 -0
- package/dist/core/distribution/install-if-absent.js +81 -0
- package/dist/core/distribution/install-if-absent.js.map +1 -0
- package/dist/core/distribution/install.d.ts.map +1 -1
- package/dist/core/distribution/install.js +5 -0
- package/dist/core/distribution/install.js.map +1 -1
- package/dist/core/distribution/migrate-docs.d.ts +64 -0
- package/dist/core/distribution/migrate-docs.d.ts.map +1 -0
- package/dist/core/distribution/migrate-docs.js +139 -0
- package/dist/core/distribution/migrate-docs.js.map +1 -0
- package/dist/core/distribution/profiles.d.ts +49 -0
- package/dist/core/distribution/profiles.d.ts.map +1 -1
- package/dist/core/distribution/profiles.js +45 -0
- package/dist/core/distribution/profiles.js.map +1 -1
- package/dist/core/distribution/update.d.ts +14 -0
- package/dist/core/distribution/update.d.ts.map +1 -1
- package/dist/core/distribution/update.js +77 -3
- package/dist/core/distribution/update.js.map +1 -1
- package/dist/core/distribution/workspace.d.ts +84 -0
- package/dist/core/distribution/workspace.d.ts.map +1 -0
- package/dist/core/distribution/workspace.js +276 -0
- package/dist/core/distribution/workspace.js.map +1 -0
- package/dist/core/exit-codes.d.ts +15 -35
- package/dist/core/exit-codes.d.ts.map +1 -1
- package/dist/core/exit-codes.js +15 -36
- package/dist/core/exit-codes.js.map +1 -1
- package/dist/core/index.d.ts +1 -6
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js +1 -7
- package/dist/core/index.js.map +1 -1
- package/package.json +17 -32
- package/templates/claude/settings.json +48 -0
- package/templates/domain/ubiquitous-language.md +28 -0
- package/templates/infra/environments.yaml +16 -0
- package/templates/infra/redaction-patterns.txt +47 -0
- package/templates/runbooks/README.md +14 -0
- package/templates/runbooks/runbook-template.md +40 -0
- package/templates/scripts/deploy-status.sh +89 -0
- package/templates/scripts/deploy-verify.sh +85 -0
- package/templates/scripts/deploy.sh +284 -0
- package/templates/scripts/release.sh +170 -0
- package/templates/scripts/rollback.sh +109 -0
- package/templates/workflows/deploy-dev.yml +66 -0
- package/templates/workflows/deploy-prod.yml +66 -0
- package/templates/workflows/rollback.yml +77 -0
- package/dist/adapters/cli/catalog-build.d.ts +0 -30
- package/dist/adapters/cli/catalog-build.d.ts.map +0 -1
- package/dist/adapters/cli/catalog-build.js +0 -73
- package/dist/adapters/cli/catalog-build.js.map +0 -1
- package/dist/adapters/cli/catalog-query.d.ts +0 -13
- package/dist/adapters/cli/catalog-query.d.ts.map +0 -1
- package/dist/adapters/cli/catalog-query.js +0 -329
- package/dist/adapters/cli/catalog-query.js.map +0 -1
- package/dist/adapters/cli/catalog-scaffold.d.ts +0 -24
- package/dist/adapters/cli/catalog-scaffold.d.ts.map +0 -1
- package/dist/adapters/cli/catalog-scaffold.js +0 -46
- package/dist/adapters/cli/catalog-scaffold.js.map +0 -1
- package/dist/adapters/cli/catalog-validate.d.ts +0 -35
- package/dist/adapters/cli/catalog-validate.d.ts.map +0 -1
- package/dist/adapters/cli/catalog-validate.js +0 -122
- package/dist/adapters/cli/catalog-validate.js.map +0 -1
- package/dist/adapters/cli/ctx-assemble.d.ts +0 -19
- package/dist/adapters/cli/ctx-assemble.d.ts.map +0 -1
- package/dist/adapters/cli/ctx-assemble.js +0 -293
- package/dist/adapters/cli/ctx-assemble.js.map +0 -1
- package/dist/adapters/cli/ctx-fetch.d.ts +0 -49
- package/dist/adapters/cli/ctx-fetch.d.ts.map +0 -1
- package/dist/adapters/cli/ctx-fetch.js +0 -267
- package/dist/adapters/cli/ctx-fetch.js.map +0 -1
- package/dist/adapters/cli/extract-all.d.ts +0 -31
- package/dist/adapters/cli/extract-all.d.ts.map +0 -1
- package/dist/adapters/cli/extract-all.js +0 -374
- package/dist/adapters/cli/extract-all.js.map +0 -1
- package/dist/adapters/cli/extract-asyncapi.d.ts +0 -26
- package/dist/adapters/cli/extract-asyncapi.d.ts.map +0 -1
- package/dist/adapters/cli/extract-asyncapi.js +0 -142
- package/dist/adapters/cli/extract-asyncapi.js.map +0 -1
- package/dist/adapters/cli/extract-component.d.ts +0 -24
- package/dist/adapters/cli/extract-component.d.ts.map +0 -1
- package/dist/adapters/cli/extract-component.js +0 -198
- package/dist/adapters/cli/extract-component.js.map +0 -1
- package/dist/adapters/cli/extract-detect.d.ts +0 -19
- package/dist/adapters/cli/extract-detect.d.ts.map +0 -1
- package/dist/adapters/cli/extract-detect.js +0 -98
- package/dist/adapters/cli/extract-detect.js.map +0 -1
- package/dist/adapters/cli/extract-openapi.d.ts +0 -29
- package/dist/adapters/cli/extract-openapi.d.ts.map +0 -1
- package/dist/adapters/cli/extract-openapi.js +0 -111
- package/dist/adapters/cli/extract-openapi.js.map +0 -1
- package/dist/adapters/cli/extract-schema.d.ts +0 -15
- package/dist/adapters/cli/extract-schema.d.ts.map +0 -1
- package/dist/adapters/cli/extract-schema.js +0 -39
- package/dist/adapters/cli/extract-schema.js.map +0 -1
- package/dist/adapters/cli/index.d.ts +0 -6
- package/dist/adapters/cli/index.d.ts.map +0 -1
- package/dist/adapters/cli/index.js +0 -5
- package/dist/adapters/cli/index.js.map +0 -1
- package/dist/adapters/cli/init.d.ts +0 -37
- package/dist/adapters/cli/init.d.ts.map +0 -1
- package/dist/adapters/cli/init.js +0 -336
- package/dist/adapters/cli/init.js.map +0 -1
- package/dist/adapters/cli/parse-args.d.ts.map +0 -1
- package/dist/adapters/cli/parse-args.js.map +0 -1
- package/dist/adapters/cli/scope-gate.d.ts +0 -25
- package/dist/adapters/cli/scope-gate.d.ts.map +0 -1
- package/dist/adapters/cli/scope-gate.js +0 -157
- package/dist/adapters/cli/scope-gate.js.map +0 -1
- package/dist/adapters/cli/scope.d.ts +0 -26
- package/dist/adapters/cli/scope.d.ts.map +0 -1
- package/dist/adapters/cli/scope.js +0 -172
- package/dist/adapters/cli/scope.js.map +0 -1
- package/dist/adapters/cli/validate-component.d.ts +0 -24
- package/dist/adapters/cli/validate-component.d.ts.map +0 -1
- package/dist/adapters/cli/validate-component.js +0 -62
- package/dist/adapters/cli/validate-component.js.map +0 -1
- package/dist/adapters/cli/verify-contract-diff.d.ts +0 -21
- package/dist/adapters/cli/verify-contract-diff.d.ts.map +0 -1
- package/dist/adapters/cli/verify-contract-diff.js +0 -69
- package/dist/adapters/cli/verify-contract-diff.js.map +0 -1
- package/dist/adapters/cli/verify-drift.d.ts +0 -24
- package/dist/adapters/cli/verify-drift.d.ts.map +0 -1
- package/dist/adapters/cli/verify-drift.js +0 -103
- package/dist/adapters/cli/verify-drift.js.map +0 -1
- package/dist/adapters/cli/verify-impact.d.ts +0 -23
- package/dist/adapters/cli/verify-impact.d.ts.map +0 -1
- package/dist/adapters/cli/verify-impact.js +0 -119
- package/dist/adapters/cli/verify-impact.js.map +0 -1
- package/dist/adapters/mcp/index.d.ts +0 -5
- package/dist/adapters/mcp/index.d.ts.map +0 -1
- package/dist/adapters/mcp/index.js +0 -2
- package/dist/adapters/mcp/index.js.map +0 -1
- package/dist/bin/dt.d.ts +0 -7
- package/dist/bin/dt.d.ts.map +0 -1
- package/dist/bin/dt.js +0 -647
- package/dist/bin/dt.js.map +0 -1
- package/dist/core/catalog/build.d.ts +0 -143
- package/dist/core/catalog/build.d.ts.map +0 -1
- package/dist/core/catalog/build.js +0 -475
- package/dist/core/catalog/build.js.map +0 -1
- package/dist/core/catalog/checks/index.d.ts +0 -18
- package/dist/core/catalog/checks/index.d.ts.map +0 -1
- package/dist/core/catalog/checks/index.js +0 -18
- package/dist/core/catalog/checks/index.js.map +0 -1
- package/dist/core/catalog/checks/v01-schema.d.ts +0 -17
- package/dist/core/catalog/checks/v01-schema.d.ts.map +0 -1
- package/dist/core/catalog/checks/v01-schema.js +0 -57
- package/dist/core/catalog/checks/v01-schema.js.map +0 -1
- package/dist/core/catalog/checks/v02-v03-identity.d.ts +0 -14
- package/dist/core/catalog/checks/v02-v03-identity.d.ts.map +0 -1
- package/dist/core/catalog/checks/v02-v03-identity.js +0 -60
- package/dist/core/catalog/checks/v02-v03-identity.js.map +0 -1
- package/dist/core/catalog/checks/v04-referential-integrity.d.ts +0 -7
- package/dist/core/catalog/checks/v04-referential-integrity.d.ts.map +0 -1
- package/dist/core/catalog/checks/v04-referential-integrity.js +0 -32
- package/dist/core/catalog/checks/v04-referential-integrity.js.map +0 -1
- package/dist/core/catalog/checks/v05-domain-existence.d.ts +0 -6
- package/dist/core/catalog/checks/v05-domain-existence.d.ts.map +0 -1
- package/dist/core/catalog/checks/v05-domain-existence.js +0 -23
- package/dist/core/catalog/checks/v05-domain-existence.js.map +0 -1
- package/dist/core/catalog/checks/v06-v07-paths.d.ts +0 -29
- package/dist/core/catalog/checks/v06-v07-paths.d.ts.map +0 -1
- package/dist/core/catalog/checks/v06-v07-paths.js +0 -107
- package/dist/core/catalog/checks/v06-v07-paths.js.map +0 -1
- package/dist/core/catalog/checks/v08-v10-contracts.d.ts +0 -13
- package/dist/core/catalog/checks/v08-v10-contracts.d.ts.map +0 -1
- package/dist/core/catalog/checks/v08-v10-contracts.js +0 -70
- package/dist/core/catalog/checks/v08-v10-contracts.js.map +0 -1
- package/dist/core/catalog/checks/v11-manual-fields.d.ts +0 -16
- package/dist/core/catalog/checks/v11-manual-fields.d.ts.map +0 -1
- package/dist/core/catalog/checks/v11-manual-fields.js +0 -60
- package/dist/core/catalog/checks/v11-manual-fields.js.map +0 -1
- package/dist/core/catalog/checks/v12-cycles.d.ts +0 -8
- package/dist/core/catalog/checks/v12-cycles.d.ts.map +0 -1
- package/dist/core/catalog/checks/v12-cycles.js +0 -28
- package/dist/core/catalog/checks/v12-cycles.js.map +0 -1
- package/dist/core/catalog/checks/v13-orphan-contracts.d.ts +0 -7
- package/dist/core/catalog/checks/v13-orphan-contracts.d.ts.map +0 -1
- package/dist/core/catalog/checks/v13-orphan-contracts.js +0 -33
- package/dist/core/catalog/checks/v13-orphan-contracts.js.map +0 -1
- package/dist/core/catalog/checks/v14-v15-lifecycle.d.ts +0 -8
- package/dist/core/catalog/checks/v14-v15-lifecycle.d.ts.map +0 -1
- package/dist/core/catalog/checks/v14-v15-lifecycle.js +0 -42
- package/dist/core/catalog/checks/v14-v15-lifecycle.js.map +0 -1
- package/dist/core/catalog/checks/v16-deprecated-consumers.d.ts +0 -7
- package/dist/core/catalog/checks/v16-deprecated-consumers.d.ts.map +0 -1
- package/dist/core/catalog/checks/v16-deprecated-consumers.js +0 -47
- package/dist/core/catalog/checks/v16-deprecated-consumers.js.map +0 -1
- package/dist/core/catalog/checks/v17-low-confidence.d.ts +0 -7
- package/dist/core/catalog/checks/v17-low-confidence.d.ts.map +0 -1
- package/dist/core/catalog/checks/v17-low-confidence.js +0 -32
- package/dist/core/catalog/checks/v17-low-confidence.js.map +0 -1
- package/dist/core/catalog/checks/v18-low-payload.d.ts +0 -7
- package/dist/core/catalog/checks/v18-low-payload.d.ts.map +0 -1
- package/dist/core/catalog/checks/v18-low-payload.js +0 -33
- package/dist/core/catalog/checks/v18-low-payload.js.map +0 -1
- package/dist/core/catalog/checks/v19-domain-membership.d.ts +0 -8
- package/dist/core/catalog/checks/v19-domain-membership.d.ts.map +0 -1
- package/dist/core/catalog/checks/v19-domain-membership.js +0 -55
- package/dist/core/catalog/checks/v19-domain-membership.js.map +0 -1
- package/dist/core/catalog/coverage.d.ts +0 -39
- package/dist/core/catalog/coverage.d.ts.map +0 -1
- package/dist/core/catalog/coverage.js +0 -62
- package/dist/core/catalog/coverage.js.map +0 -1
- package/dist/core/catalog/graph.d.ts +0 -49
- package/dist/core/catalog/graph.d.ts.map +0 -1
- package/dist/core/catalog/graph.js +0 -114
- package/dist/core/catalog/graph.js.map +0 -1
- package/dist/core/catalog/index-model.d.ts +0 -96
- package/dist/core/catalog/index-model.d.ts.map +0 -1
- package/dist/core/catalog/index-model.js +0 -8
- package/dist/core/catalog/index-model.js.map +0 -1
- package/dist/core/catalog/index.d.ts +0 -5
- package/dist/core/catalog/index.d.ts.map +0 -1
- package/dist/core/catalog/index.js +0 -2
- package/dist/core/catalog/index.js.map +0 -1
- package/dist/core/catalog/queries.d.ts +0 -69
- package/dist/core/catalog/queries.d.ts.map +0 -1
- package/dist/core/catalog/queries.js +0 -165
- package/dist/core/catalog/queries.js.map +0 -1
- package/dist/core/catalog/resolve.d.ts +0 -47
- package/dist/core/catalog/resolve.d.ts.map +0 -1
- package/dist/core/catalog/resolve.js +0 -318
- package/dist/core/catalog/resolve.js.map +0 -1
- package/dist/core/catalog/scaffold.d.ts +0 -31
- package/dist/core/catalog/scaffold.d.ts.map +0 -1
- package/dist/core/catalog/scaffold.js +0 -141
- package/dist/core/catalog/scaffold.js.map +0 -1
- package/dist/core/catalog/validate-component.d.ts +0 -50
- package/dist/core/catalog/validate-component.d.ts.map +0 -1
- package/dist/core/catalog/validate-component.js +0 -105
- package/dist/core/catalog/validate-component.js.map +0 -1
- package/dist/core/catalog/validate.d.ts +0 -71
- package/dist/core/catalog/validate.d.ts.map +0 -1
- package/dist/core/catalog/validate.js +0 -103
- package/dist/core/catalog/validate.js.map +0 -1
- package/dist/core/context/assemble.d.ts +0 -126
- package/dist/core/context/assemble.d.ts.map +0 -1
- package/dist/core/context/assemble.js +0 -197
- package/dist/core/context/assemble.js.map +0 -1
- package/dist/core/context/cache.d.ts +0 -60
- package/dist/core/context/cache.d.ts.map +0 -1
- package/dist/core/context/cache.js +0 -236
- package/dist/core/context/cache.js.map +0 -1
- package/dist/core/context/exit-codes.d.ts +0 -28
- package/dist/core/context/exit-codes.d.ts.map +0 -1
- package/dist/core/context/exit-codes.js +0 -28
- package/dist/core/context/exit-codes.js.map +0 -1
- package/dist/core/context/fetch.d.ts +0 -55
- package/dist/core/context/fetch.d.ts.map +0 -1
- package/dist/core/context/fetch.js +0 -112
- package/dist/core/context/fetch.js.map +0 -1
- package/dist/core/context/index.d.ts +0 -11
- package/dist/core/context/index.d.ts.map +0 -1
- package/dist/core/context/index.js +0 -8
- package/dist/core/context/index.js.map +0 -1
- package/dist/core/context/init.d.ts +0 -179
- package/dist/core/context/init.d.ts.map +0 -1
- package/dist/core/context/init.js +0 -532
- package/dist/core/context/init.js.map +0 -1
- package/dist/core/context/layers/architecture-layer.d.ts +0 -13
- package/dist/core/context/layers/architecture-layer.d.ts.map +0 -1
- package/dist/core/context/layers/architecture-layer.js +0 -24
- package/dist/core/context/layers/architecture-layer.js.map +0 -1
- package/dist/core/context/layers/contracts-layer.d.ts +0 -13
- package/dist/core/context/layers/contracts-layer.d.ts.map +0 -1
- package/dist/core/context/layers/contracts-layer.js +0 -83
- package/dist/core/context/layers/contracts-layer.js.map +0 -1
- package/dist/core/context/layers/conventions-delta-layer.d.ts +0 -13
- package/dist/core/context/layers/conventions-delta-layer.d.ts.map +0 -1
- package/dist/core/context/layers/conventions-delta-layer.js +0 -37
- package/dist/core/context/layers/conventions-delta-layer.js.map +0 -1
- package/dist/core/context/layers/flow-layer.d.ts +0 -14
- package/dist/core/context/layers/flow-layer.d.ts.map +0 -1
- package/dist/core/context/layers/flow-layer.js +0 -61
- package/dist/core/context/layers/flow-layer.js.map +0 -1
- package/dist/core/context/layers/index-layer.d.ts +0 -13
- package/dist/core/context/layers/index-layer.d.ts.map +0 -1
- package/dist/core/context/layers/index-layer.js +0 -77
- package/dist/core/context/layers/index-layer.js.map +0 -1
- package/dist/core/context/layers/primary-layer.d.ts +0 -16
- package/dist/core/context/layers/primary-layer.d.ts.map +0 -1
- package/dist/core/context/layers/primary-layer.js +0 -61
- package/dist/core/context/layers/primary-layer.js.map +0 -1
- package/dist/core/context/layers/secondary-layer.d.ts +0 -19
- package/dist/core/context/layers/secondary-layer.d.ts.map +0 -1
- package/dist/core/context/layers/secondary-layer.js +0 -52
- package/dist/core/context/layers/secondary-layer.js.map +0 -1
- package/dist/core/context/session-lock.d.ts +0 -114
- package/dist/core/context/session-lock.d.ts.map +0 -1
- package/dist/core/context/session-lock.js +0 -90
- package/dist/core/context/session-lock.js.map +0 -1
- package/dist/core/context/tokens.d.ts +0 -35
- package/dist/core/context/tokens.d.ts.map +0 -1
- package/dist/core/context/tokens.js +0 -88
- package/dist/core/context/tokens.js.map +0 -1
- package/dist/core/extract/asyncapi/declared.d.ts +0 -19
- package/dist/core/extract/asyncapi/declared.d.ts.map +0 -1
- package/dist/core/extract/asyncapi/declared.js +0 -168
- package/dist/core/extract/asyncapi/declared.js.map +0 -1
- package/dist/core/extract/asyncapi/index.d.ts +0 -12
- package/dist/core/extract/asyncapi/index.d.ts.map +0 -1
- package/dist/core/extract/asyncapi/index.js +0 -8
- package/dist/core/extract/asyncapi/index.js.map +0 -1
- package/dist/core/extract/asyncapi/payloads.d.ts +0 -20
- package/dist/core/extract/asyncapi/payloads.d.ts.map +0 -1
- package/dist/core/extract/asyncapi/payloads.js +0 -421
- package/dist/core/extract/asyncapi/payloads.js.map +0 -1
- package/dist/core/extract/asyncapi/topics.d.ts +0 -27
- package/dist/core/extract/asyncapi/topics.d.ts.map +0 -1
- package/dist/core/extract/asyncapi/topics.js +0 -368
- package/dist/core/extract/asyncapi/topics.js.map +0 -1
- package/dist/core/extract/asyncapi/types.d.ts +0 -129
- package/dist/core/extract/asyncapi/types.d.ts.map +0 -1
- package/dist/core/extract/asyncapi/types.js +0 -5
- package/dist/core/extract/asyncapi/types.js.map +0 -1
- package/dist/core/extract/asyncapi/validate.d.ts +0 -29
- package/dist/core/extract/asyncapi/validate.d.ts.map +0 -1
- package/dist/core/extract/asyncapi/validate.js +0 -156
- package/dist/core/extract/asyncapi/validate.js.map +0 -1
- package/dist/core/extract/component.d.ts +0 -204
- package/dist/core/extract/component.d.ts.map +0 -1
- package/dist/core/extract/component.js +0 -258
- package/dist/core/extract/component.js.map +0 -1
- package/dist/core/extract/detect.d.ts +0 -35
- package/dist/core/extract/detect.d.ts.map +0 -1
- package/dist/core/extract/detect.js +0 -89
- package/dist/core/extract/detect.js.map +0 -1
- package/dist/core/extract/index.d.ts +0 -12
- package/dist/core/extract/index.d.ts.map +0 -1
- package/dist/core/extract/index.js +0 -6
- package/dist/core/extract/index.js.map +0 -1
- package/dist/core/extract/ladder.d.ts +0 -79
- package/dist/core/extract/ladder.d.ts.map +0 -1
- package/dist/core/extract/ladder.js +0 -70
- package/dist/core/extract/ladder.js.map +0 -1
- package/dist/core/extract/openapi/index.d.ts +0 -43
- package/dist/core/extract/openapi/index.d.ts.map +0 -1
- package/dist/core/extract/openapi/index.js +0 -142
- package/dist/core/extract/openapi/index.js.map +0 -1
- package/dist/core/extract/openapi/route1.d.ts +0 -36
- package/dist/core/extract/openapi/route1.d.ts.map +0 -1
- package/dist/core/extract/openapi/route1.js +0 -333
- package/dist/core/extract/openapi/route1.js.map +0 -1
- package/dist/core/extract/openapi/route2-introspect.d.ts +0 -18
- package/dist/core/extract/openapi/route2-introspect.d.ts.map +0 -1
- package/dist/core/extract/openapi/route2-introspect.js +0 -249
- package/dist/core/extract/openapi/route2-introspect.js.map +0 -1
- package/dist/core/extract/openapi/route2.d.ts +0 -69
- package/dist/core/extract/openapi/route2.d.ts.map +0 -1
- package/dist/core/extract/openapi/route2.js +0 -211
- package/dist/core/extract/openapi/route2.js.map +0 -1
- package/dist/core/extract/openapi/route3.d.ts +0 -26
- package/dist/core/extract/openapi/route3.d.ts.map +0 -1
- package/dist/core/extract/openapi/route3.js +0 -737
- package/dist/core/extract/openapi/route3.js.map +0 -1
- package/dist/core/extract/openapi/types.d.ts +0 -125
- package/dist/core/extract/openapi/types.d.ts.map +0 -1
- package/dist/core/extract/openapi/types.js +0 -5
- package/dist/core/extract/openapi/types.js.map +0 -1
- package/dist/core/extract/openapi/validate.d.ts +0 -29
- package/dist/core/extract/openapi/validate.d.ts.map +0 -1
- package/dist/core/extract/openapi/validate.js +0 -200
- package/dist/core/extract/openapi/validate.js.map +0 -1
- package/dist/core/extract/orm/drizzle.d.ts +0 -20
- package/dist/core/extract/orm/drizzle.d.ts.map +0 -1
- package/dist/core/extract/orm/drizzle.js +0 -283
- package/dist/core/extract/orm/drizzle.js.map +0 -1
- package/dist/core/extract/orm/information-schema.d.ts +0 -26
- package/dist/core/extract/orm/information-schema.d.ts.map +0 -1
- package/dist/core/extract/orm/information-schema.js +0 -142
- package/dist/core/extract/orm/information-schema.js.map +0 -1
- package/dist/core/extract/orm/prisma.d.ts +0 -23
- package/dist/core/extract/orm/prisma.d.ts.map +0 -1
- package/dist/core/extract/orm/prisma.js +0 -234
- package/dist/core/extract/orm/prisma.js.map +0 -1
- package/dist/core/extract/orm/typeorm.d.ts +0 -22
- package/dist/core/extract/orm/typeorm.d.ts.map +0 -1
- package/dist/core/extract/orm/typeorm.js +0 -269
- package/dist/core/extract/orm/typeorm.js.map +0 -1
- package/dist/core/extract/orm/types.d.ts +0 -97
- package/dist/core/extract/orm/types.d.ts.map +0 -1
- package/dist/core/extract/orm/types.js +0 -6
- package/dist/core/extract/orm/types.js.map +0 -1
- package/dist/core/extract/prompt.d.ts +0 -21
- package/dist/core/extract/prompt.d.ts.map +0 -1
- package/dist/core/extract/prompt.js +0 -79
- package/dist/core/extract/prompt.js.map +0 -1
- package/dist/core/extract/provider.d.ts +0 -121
- package/dist/core/extract/provider.d.ts.map +0 -1
- package/dist/core/extract/provider.js +0 -6
- package/dist/core/extract/provider.js.map +0 -1
- package/dist/core/extract/providers/node-ts.d.ts +0 -69
- package/dist/core/extract/providers/node-ts.d.ts.map +0 -1
- package/dist/core/extract/providers/node-ts.js +0 -320
- package/dist/core/extract/providers/node-ts.js.map +0 -1
- package/dist/core/extract/render/schema-md.d.ts +0 -16
- package/dist/core/extract/render/schema-md.d.ts.map +0 -1
- package/dist/core/extract/render/schema-md.js +0 -140
- package/dist/core/extract/render/schema-md.js.map +0 -1
- package/dist/core/extract/report.d.ts +0 -125
- package/dist/core/extract/report.d.ts.map +0 -1
- package/dist/core/extract/report.js +0 -52
- package/dist/core/extract/report.js.map +0 -1
- package/dist/core/extract/schema.d.ts +0 -34
- package/dist/core/extract/schema.d.ts.map +0 -1
- package/dist/core/extract/schema.js +0 -146
- package/dist/core/extract/schema.js.map +0 -1
- package/dist/core/extract/workspaces.d.ts +0 -33
- package/dist/core/extract/workspaces.d.ts.map +0 -1
- package/dist/core/extract/workspaces.js +0 -193
- package/dist/core/extract/workspaces.js.map +0 -1
- package/dist/core/providers/index.d.ts +0 -6
- package/dist/core/providers/index.d.ts.map +0 -1
- package/dist/core/providers/index.js +0 -2
- package/dist/core/providers/index.js.map +0 -1
- package/dist/core/providers/tracker.d.ts +0 -74
- package/dist/core/providers/tracker.d.ts.map +0 -1
- package/dist/core/providers/tracker.js +0 -38
- package/dist/core/providers/tracker.js.map +0 -1
- package/dist/core/scope/calibration.d.ts +0 -25
- package/dist/core/scope/calibration.d.ts.map +0 -1
- package/dist/core/scope/calibration.js +0 -52
- package/dist/core/scope/calibration.js.map +0 -1
- package/dist/core/scope/closure.d.ts +0 -31
- package/dist/core/scope/closure.d.ts.map +0 -1
- package/dist/core/scope/closure.js +0 -68
- package/dist/core/scope/closure.js.map +0 -1
- package/dist/core/scope/gate.d.ts +0 -41
- package/dist/core/scope/gate.d.ts.map +0 -1
- package/dist/core/scope/gate.js +0 -165
- package/dist/core/scope/gate.js.map +0 -1
- package/dist/core/scope/index.d.ts +0 -18
- package/dist/core/scope/index.d.ts.map +0 -1
- package/dist/core/scope/index.js +0 -12
- package/dist/core/scope/index.js.map +0 -1
- package/dist/core/scope/partition.d.ts +0 -36
- package/dist/core/scope/partition.d.ts.map +0 -1
- package/dist/core/scope/partition.js +0 -78
- package/dist/core/scope/partition.js.map +0 -1
- package/dist/core/scope/prompt.d.ts +0 -39
- package/dist/core/scope/prompt.d.ts.map +0 -1
- package/dist/core/scope/prompt.js +0 -123
- package/dist/core/scope/prompt.js.map +0 -1
- package/dist/core/scope/scoping.d.ts +0 -52
- package/dist/core/scope/scoping.d.ts.map +0 -1
- package/dist/core/scope/scoping.js +0 -99
- package/dist/core/scope/scoping.js.map +0 -1
- package/dist/core/scope/types.d.ts +0 -77
- package/dist/core/scope/types.d.ts.map +0 -1
- package/dist/core/scope/types.js +0 -5
- package/dist/core/scope/types.js.map +0 -1
- package/dist/core/scope/validate.d.ts +0 -47
- package/dist/core/scope/validate.d.ts.map +0 -1
- package/dist/core/scope/validate.js +0 -90
- package/dist/core/scope/validate.js.map +0 -1
- package/dist/core/verify/asyncapi-diff.d.ts +0 -34
- package/dist/core/verify/asyncapi-diff.d.ts.map +0 -1
- package/dist/core/verify/asyncapi-diff.js +0 -209
- package/dist/core/verify/asyncapi-diff.js.map +0 -1
- package/dist/core/verify/contract-diff.d.ts +0 -39
- package/dist/core/verify/contract-diff.d.ts.map +0 -1
- package/dist/core/verify/contract-diff.js +0 -63
- package/dist/core/verify/contract-diff.js.map +0 -1
- package/dist/core/verify/drift.d.ts +0 -47
- package/dist/core/verify/drift.d.ts.map +0 -1
- package/dist/core/verify/drift.js +0 -122
- package/dist/core/verify/drift.js.map +0 -1
- package/dist/core/verify/impact.d.ts +0 -22
- package/dist/core/verify/impact.d.ts.map +0 -1
- package/dist/core/verify/impact.js +0 -93
- package/dist/core/verify/impact.js.map +0 -1
- package/dist/core/verify/index.d.ts +0 -10
- package/dist/core/verify/index.d.ts.map +0 -1
- package/dist/core/verify/index.js +0 -9
- package/dist/core/verify/index.js.map +0 -1
- package/dist/core/verify/openapi-diff.d.ts +0 -29
- package/dist/core/verify/openapi-diff.d.ts.map +0 -1
- package/dist/core/verify/openapi-diff.js +0 -291
- package/dist/core/verify/openapi-diff.js.map +0 -1
- package/dist/core/verify/types.d.ts +0 -138
- package/dist/core/verify/types.d.ts.map +0 -1
- package/dist/core/verify/types.js +0 -5
- package/dist/core/verify/types.js.map +0 -1
- package/schemas/component.schema.json +0 -203
- package/schemas/flow.schema.json +0 -75
- package/schemas/scope-output.schema.json +0 -62
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Activity: Grill
|
|
2
|
+
|
|
3
|
+
Interview the user one question at a time — depth-first, resolve-before-ask, one recommendation per question — until every open design question is resolved and the user has explicitly confirmed shared understanding. `activity-grill` is a sub-skill invoked by `activity-refine` (WHAT phase, Issue Mode) and `activity-generate-spec` (HOW phase); it has no top-level entry point of its own.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
|
|
8
|
+
|
|
9
|
+
## Goal
|
|
10
|
+
|
|
11
|
+
Walk the design tree for a feature or issue to a state of genuine shared understanding, recorded as an auditable decision log, before the invoking skill drafts anything. The engine never batches questions, never infers confirmation from tone, and never silently decides on the user's behalf.
|
|
12
|
+
|
|
13
|
+
## Invocation
|
|
14
|
+
|
|
15
|
+
The caller passes:
|
|
16
|
+
|
|
17
|
+
- `phase` — `"WHAT"` (invoked by `activity-refine` PRD Creation mode, before drafting) or `"HOW"` (invoked by `activity-generate-spec`, before drafting). Both phases share one continuing ID space in the decision log — there is no phase-local restart (FR-7).
|
|
18
|
+
- `cap` — the question cap for this phase (see Cap Configuration below).
|
|
19
|
+
- `mode` — `"feature"` (default) or `"issue"` (Issue Mode, invoked by `activity-refine` Issue Refinement mode). Issue Mode is invoked without a `phase` argument — `activity-refine` passes `mode` and `cap` only.
|
|
20
|
+
- `feature` — the slug used to name `workstream/decisions-<feature>.md`.
|
|
21
|
+
|
|
22
|
+
## Context
|
|
23
|
+
|
|
24
|
+
This skill has no caller-specific behavior of its own — `activity-refine` and `activity-generate-spec` decide when to invoke it and what to do with a satisfied exit gate. This skill owns only: the question loop, resolve-before-ask precedence, the append-per-resolution write, the cap/summary/exit-gate mechanics, and the Issue Mode variant.
|
|
25
|
+
|
|
26
|
+
## Write Authority
|
|
27
|
+
|
|
28
|
+
- `workstream/decisions-<feature>.md` — append one row per resolved question, immediately (FR-4). Never batch writes to the end of a session.
|
|
29
|
+
- Nothing else. No PRD, spec, task list, code, or `/DESIGN.md` file may be created or modified by this skill.
|
|
30
|
+
|
|
31
|
+
## Process
|
|
32
|
+
|
|
33
|
+
### 1. One question, one recommendation, per turn (FR-1)
|
|
34
|
+
|
|
35
|
+
The skill never batches questions in one turn. Each question the skill cannot resolve itself is presented alone, with exactly one recommended answer attached, so the user can accept the recommendation or state a different answer in a single reply.
|
|
36
|
+
|
|
37
|
+
### 2. Depth-first traversal (FR-2)
|
|
38
|
+
|
|
39
|
+
A branch (e.g., `grilling/placement`, `simplicity/content` — the existing `Branch` column in `decisions-<feature>.md` already models this) is fully resolved, including any decision it depends on, before a sibling branch opens. Do not open a new branch while the current one has unresolved dependents.
|
|
40
|
+
|
|
41
|
+
### 3. Resolve-before-ask (FR-3)
|
|
42
|
+
|
|
43
|
+
Before asking the user anything, check in this order:
|
|
44
|
+
|
|
45
|
+
1. **Codebase directly** — `Read`/`Grep`/`Glob` for single-file questions (e.g., "does this config already exist?").
|
|
46
|
+
2. **`docs/product.md` / `docs/tech.md` / the glossary** for standing decisions already recorded there. All three are read here and written by none of them — the glossary in particular is consulted, never edited, in every mode (D-61).
|
|
47
|
+
3. **Prior `decisions-*.md` files** for a matching answer — mandatory in Issue Mode (FR-10), optional-but-recommended in Feature Mode.
|
|
48
|
+
4. **A bounded `researcher` call** — only when the question needs multi-slice evidence a single file read cannot supply, AND only if a fresh, non-stale pre-step `/workstream/research-*.md` artifact (if any) does not already cover it (D-56). At most one `researcher` call total per phase, shared with the caller's own conditional pre-step budget (ADR-004) — `activity-grill` is a second possible caller of `researcher`, not a second guaranteed invocation.
|
|
49
|
+
|
|
50
|
+
Only if none of the four resolve the question does the skill ask the user. A question whose codebase answer is ambiguous (multiple conflicting sources) is still asked to the user — the skill never guesses.
|
|
51
|
+
|
|
52
|
+
### 3a. Vocabulary conflicts are questions, never resolutions (FR-21)
|
|
53
|
+
|
|
54
|
+
This rule belongs to the two invocations where the feature's domain language is still being settled: the WHAT phase (`phase="WHAT"`) and Issue Mode (`mode="issue"`, which `activity-refine` invokes without a `phase` argument — see step 10). It does not run in the HOW phase.
|
|
55
|
+
|
|
56
|
+
Once the open branch reaches what the feature _is_, ask the user plainly **which domain concepts this feature introduces or changes** — one question, with a recommendation, like every other. For each term the user names, consult the glossary (step 3's second source) and check two things:
|
|
57
|
+
|
|
58
|
+
1. **The same term with a different definition** — the glossary already defines the term, and the definition the user just gave is not the recorded one.
|
|
59
|
+
2. **The term appearing in another term's forbidden synonyms** — the term is not an entry of its own, but an existing entry names it as a synonym it forbids.
|
|
60
|
+
|
|
61
|
+
Either hit is **surfaced as a question** with exactly one recommendation, and the user's answer becomes a `D-NN` row like any other resolution (step 4). A conflict is **never resolved silently**: the skill does not adopt the glossary's definition, does not adopt the user's, and does not quietly rename or merge the term. The term's `Status in glossary` is then `conflict → D-NN` in the drafted PRD — written later, by the caller, not here.
|
|
62
|
+
|
|
63
|
+
Two cases resolve without a new question, or with one question rather than several:
|
|
64
|
+
|
|
65
|
+
- **Same term, same definition.** The glossary already says what the user just said; nothing is asked and the existing term is reused. That is resolve-before-ask working (step 3), not a conflict.
|
|
66
|
+
- **One term forbidden by two entries.** A term named as a forbidden synonym by two different glossary entries raises **one** question naming both owning terms — one conflict with two owners, not two conflicts. Batching remains forbidden (FR-1).
|
|
67
|
+
|
|
68
|
+
The skill reads the glossary and writes nothing to it, in every mode and every phase — see Write Authority.
|
|
69
|
+
|
|
70
|
+
### 4. Append-per-resolution (FR-4)
|
|
71
|
+
|
|
72
|
+
Every resolved question — whether asked to the user or self-resolved via step 3 — becomes one row in `workstream/decisions-<feature>.md`, written immediately, not batched at the end of the session. A self-resolved row still gets a unique, never-reused `D-NN` ID; its `Accepted rec.` column is `n/a` and its `Answer` column states what was found and where (file, section, or prior decision ID). Row columns: ID, Phase, Branch, Question, Recommended, Answer, Accepted rec., Supersedes, Author, Date — the existing `decisions-<feature>.md` schema, unchanged by this skill.
|
|
73
|
+
|
|
74
|
+
### 5. Qualified citation form (FR-5)
|
|
75
|
+
|
|
76
|
+
Cite a decision as `<feature>#D-NN` everywhere outside that decision's own log file, and as the unqualified `D-NN` inside it — the convention `decisions-shared-understanding.md` already uses. A corrected decision never overwrites or renumbers its original row; it gets a new row whose `Supersedes` column names the superseded ID.
|
|
77
|
+
|
|
78
|
+
### 6. Decision-tree summary cadence (FR-6)
|
|
79
|
+
|
|
80
|
+
Every 10th resolved question, at the cap, and at the exit-gate attempt, the skill prints a decision-tree summary: resolved branches (each with its `D-NN`), the current branch, and the remaining open list. This is the only place the skill surfaces multiple prior questions at once — it is a summary of what already happened, not a new batch of questions.
|
|
81
|
+
|
|
82
|
+
### 7. Two-phase mode (FR-7)
|
|
83
|
+
|
|
84
|
+
`activity-grill(phase="WHAT")` runs before `activity-refine` drafts a PRD; `activity-grill(phase="HOW")` runs before `activity-generate-spec` drafts a specification. Each phase's questions continue the single ID space already present in the feature's decision log (e.g., D-01…D-27 WHAT, D-28… HOW) — never a phase-local restart.
|
|
85
|
+
|
|
86
|
+
### 8. Hard exit gate (FR-8)
|
|
87
|
+
|
|
88
|
+
The exit gate is satisfied only when **both** hold:
|
|
89
|
+
|
|
90
|
+
- The open-questions list is empty, **and**
|
|
91
|
+
- The user has made an explicit statement of shared understanding (e.g., "I understand, proceed" / "I confirm").
|
|
92
|
+
|
|
93
|
+
A "sounds good," an emoji, or silence after a decision-tree summary does **not** satisfy the gate. When the open list is empty, the skill asks directly: _"The open list is empty. Do you confirm shared understanding so I can draft?"_ If the user's reply is not an explicit confirmation, the skill re-asks the same direct question rather than treating the reply as consent — the gate is never inferred from tone or silence.
|
|
94
|
+
|
|
95
|
+
An empty open-questions list at invocation (nothing to grill) does not silently skip this gate — the direct confirmation question is still asked and must still be explicitly answered.
|
|
96
|
+
|
|
97
|
+
### 9. Configurable, enforced cap (FR-9)
|
|
98
|
+
|
|
99
|
+
Default cap: **25/25/8** — 25 questions per phase in Feature Mode (WHAT, HOW), 8 in Issue Mode. Read the configured cap from `docs/tech.md` § Grilling if that subsection exists; otherwise use the hardcoded default. If the configured value is 0 or non-positive, treat it as misconfiguration: fall back to the hardcoded default and note the fallback in the next decision-tree summary.
|
|
100
|
+
|
|
101
|
+
On reaching the cap, the skill presents the open list and asks the user to **continue (raise the cap) or stop (draft with what's settled, leaving the rest as recorded Open Questions)**. It never auto-continues and never auto-stops — the choice belongs to the user every time the cap is reached.
|
|
102
|
+
|
|
103
|
+
### 10. Issue Mode constraints (FR-10)
|
|
104
|
+
|
|
105
|
+
When `mode="issue"`:
|
|
106
|
+
|
|
107
|
+
- **Glossary is read-only.** No new term proposals. The glossary is consulted for resolve-before-ask and for the conflict checks in step 3a; a term the issue needs and the glossary lacks is a question for the user, never an edit made here.
|
|
108
|
+
- **Scope is limited** to what the issue changes relative to current behavior — do not open branches outside that delta.
|
|
109
|
+
- **Prior-decision reuse is mandatory, not optional.** Before asking, search prior decisions from _any_ feature's `decisions-*.md` for a reusable answer. The scan is keyword-gated: only logs whose `Branch` or `Question` text shares a term with the issue description are read, keeping the lookup bounded as the number of logs grows. A reused answer is cited in qualified form (`<other-feature>#D-NN`) and is not re-asked.
|
|
110
|
+
- The cap is 8, per the default above (or the configured `docs/tech.md` § Grilling issue-mode value).
|
|
111
|
+
|
|
112
|
+
### 11. Assumption-testing reminder (FR-11, SHOULD)
|
|
113
|
+
|
|
114
|
+
Once per phase, the skill states plainly that accepting every recommendation reproduces its own assumptions rather than testing them — a reminder, not a gate, and not repeated more than once per phase.
|
|
115
|
+
|
|
116
|
+
## Cap Configuration
|
|
117
|
+
|
|
118
|
+
| Mode | Default cap | Configured source |
|
|
119
|
+
| ------------------ | ----------- | ------------------------------------- |
|
|
120
|
+
| Feature Mode, WHAT | 25 | `docs/tech.md` § Grilling, if present |
|
|
121
|
+
| Feature Mode, HOW | 25 | `docs/tech.md` § Grilling, if present |
|
|
122
|
+
| Issue Mode | 8 | `docs/tech.md` § Grilling, if present |
|
|
123
|
+
|
|
124
|
+
The 25/25/8 defaults apply whenever `docs/tech.md` has no § Grilling subsection, or the subsection's value for this mode is missing, zero, or negative (misconfiguration fallback, noted in the next decision-tree summary).
|
|
125
|
+
|
|
126
|
+
## Session State (D-54)
|
|
127
|
+
|
|
128
|
+
The open-questions list and the current depth-first tree position live only in the invoking conversation's turn-by-turn context. `workstream/decisions-<feature>.md` is the only persistent artifact this skill writes, appended to immediately per resolved question (FR-4). **Do not** create a separate `grill-state-<feature>.md` or any other working file to track session progress. If a session is interrupted and resumed, re-derive the open list by diffing what the PRD/spec still needs settled against what the decision log already has — the log is the source of truth for what is already resolved.
|
|
129
|
+
|
|
130
|
+
## Attribution (D-53)
|
|
131
|
+
|
|
132
|
+
No attribution is added anywhere in this skill for the `grill-me` interview pattern. This implementation is written independently from the PRD's own description of the desired behavior, not derived from any one repository's source; there is no single canonical `grill-me` project to credit, and several independent, differently-licensed reimplementations exist. Do not add a header credit line, footer note, or inline reference naming grill-me or any of its forks.
|
|
133
|
+
|
|
134
|
+
## Output
|
|
135
|
+
|
|
136
|
+
- Zero or more new rows appended to `workstream/decisions-<feature>.md`, one per resolved question, written as each question resolves.
|
|
137
|
+
- A returned exit-gate status to the caller: satisfied (open list empty and explicit confirmation received) or not yet satisfied.
|
|
138
|
+
- Zero or more decision-tree summaries printed to the conversation at the required cadence (every 10th resolution, cap, exit attempt).
|
|
139
|
+
|
|
140
|
+
## Non-Goals
|
|
141
|
+
|
|
142
|
+
- Not a drafting skill — produces no PRD, spec, or task-list content itself.
|
|
143
|
+
- Not a top-level entry point — only `activity-refine` and `activity-generate-spec` invoke it.
|
|
144
|
+
- Not a glossary editor — the glossary is read in every mode and written in none. Proposing a term into it is `activity-refine`'s write, made on the user's approval of a PRD, never mid-interview (D-61).
|
|
145
|
+
- Not a second, independent `researcher` budget — shares the phase's existing conditional pre-step budget (D-56, ADR-004).
|
|
@@ -12,6 +12,27 @@ Guide an AI assistant in establishing the foundational documents for a project:
|
|
|
12
12
|
|
|
13
13
|
Run this activity **once per project** (or when a major strategic or technical pivot occurs).
|
|
14
14
|
|
|
15
|
+
## Foundation Document Names
|
|
16
|
+
|
|
17
|
+
The canonical names are **`docs/product.md`** and **`docs/tech.md`**. Create and reference those names only.
|
|
18
|
+
|
|
19
|
+
**Fallback, one release cycle (FR-45, `shared-understanding#D-42`).** These documents were renamed from `docs/product-context.md` and `docs/technical-guidelines.md`. A consumer repository installed before the rename still carries the old names, and `dev-tasks update` never renames a consumer-owned file on its own. So when reading a foundation document: resolve `docs/product.md` first and fall back to `docs/product-context.md` only if the new name is absent; likewise `docs/tech.md`, then `docs/technical-guidelines.md`. When writing, always write the new name.
|
|
20
|
+
|
|
21
|
+
On encountering the old names, propose `dev-tasks migrate docs`, which performs the rename with content unchanged. Do not rename a consumer's files without being asked. The fallback is removed one release cycle after the rename ships (tracked in issue #201); after that the proposal is the only path.
|
|
22
|
+
|
|
23
|
+
## Repository Setup — Branch Protection (Required)
|
|
24
|
+
|
|
25
|
+
Before or alongside establishing the foundation documents, verify the repository's default branch has GitHub branch protection configured. This is not optional hardening — it is the actual gate for "no agent merges into the default branch." Every hook shipped with dev-tasks (`git-guard.sh`, `branch-guard.sh`, and their Kiro equivalents) is a best-effort, advisory, local check that can be evaded by a sufficiently creative command or tool-input shape, and Copilot has no hook system at all; only a server-side branch protection rule is unbypassable by any tool surface.
|
|
26
|
+
|
|
27
|
+
Check with `gh api repos/<owner>/<repo>/branches/<default-branch>/protection` (a 404 means it is not configured). If missing, tell the user and offer to configure it:
|
|
28
|
+
|
|
29
|
+
- Require a pull request before merging
|
|
30
|
+
- Require at least 1 approving review
|
|
31
|
+
- Require status checks to pass before merging
|
|
32
|
+
- Disable force-pushes and branch deletion on the default branch
|
|
33
|
+
|
|
34
|
+
See the README "Configure branch protection" step for the exact `gh api` invocation. You **MUST NOT** proceed to treat the project as fully initialized while branch protection remains unconfigured without the user's explicit acknowledgment.
|
|
35
|
+
|
|
15
36
|
## Document Changelog Convention
|
|
16
37
|
|
|
17
38
|
Every document produced by this activity **MUST** include a **Changelog** table as the **first section** after the document title. The changelog tracks the version history of the document.
|
|
@@ -31,90 +52,119 @@ Every document produced by this activity **MUST** include a **Changelog** table
|
|
|
31
52
|
|
|
32
53
|
---
|
|
33
54
|
|
|
34
|
-
## Mode Detection
|
|
55
|
+
## Mode Detection
|
|
35
56
|
|
|
36
57
|
Before starting the interview, the skill **MUST** detect the repository mode and route accordingly. The detection logic is:
|
|
37
58
|
|
|
38
|
-
1. **
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
> **Precedence:** If both `component.json` AND `/docs` exist, multi-repo mode wins — `component.json` is the authoritative signal.
|
|
59
|
+
1. **Documented-repository mode:** `/docs` directory exists → interview + direct docs generation.
|
|
60
|
+
This mode is about whether documentation exists, not about how many packages the repository has. Repository _shape_ (single-package or monorepo) is detected separately — see Repository Shape Detection below. The mode was called "Mono-Repo" until `shared-understanding#D-44` renamed it to free the term.
|
|
61
|
+
2. **Undocumented / greenfield mode:** no `/docs` → investigation-first flow to bootstrap documentation from the codebase, then interview.
|
|
43
62
|
|
|
44
63
|
---
|
|
45
64
|
|
|
46
|
-
## Mode A —
|
|
65
|
+
## Mode A — Documented Repository (Current Flow)
|
|
47
66
|
|
|
48
|
-
When `
|
|
67
|
+
When `/docs` exists, the skill follows the **existing single-repo flow** unchanged.
|
|
49
68
|
|
|
50
69
|
### Process
|
|
51
70
|
|
|
52
|
-
1. **
|
|
53
|
-
2. **
|
|
71
|
+
1. **Receive Initial Brief:** The user describes the product, project, or technology stack.
|
|
72
|
+
2. **Ask Clarifying Questions:** Gather information for both product context and technical guidelines in a single interview. Group questions by domain.
|
|
73
|
+
3. **Generate Product Document:** Create `docs/product.md` using the structure below.
|
|
74
|
+
4. **Generate Technical Document:** Create `docs/tech.md` using the structure below.
|
|
75
|
+
5. **Save Output:** Save both documents in `/docs/` and present them for user review.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Mode B — Undocumented / Greenfield
|
|
54
80
|
|
|
55
|
-
|
|
56
|
-
| --------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
57
|
-
| `0` | Success — bundle emitted | Load bundle files in numeric order. Present `review_flags` (if any) to the user before proceeding to planning. Continue to the interview for product context and technical guidelines using the bundle as input. |
|
|
58
|
-
| `7` | Gate abort — partition proposal | Present the partition proposal to the user. Explain that the scope is too broad and needs to be split. **Stop** — do not proceed to planning. |
|
|
59
|
-
| `9` | Stale catalog index | Inform the user that the catalog index is stale and needs to be rebuilt (e.g., `dt catalog build`). **Stop** — do not proceed. |
|
|
60
|
-
| `10` | Invalid scope after LLM retry | Inform the user that automatic scoping failed. Suggest running with `--components` for manual scope. **Stop.** |
|
|
61
|
-
| `11` | No candidates found | Inform the user that no components matched the task description. Suggest refining the task text or using `--components`. **Stop.** |
|
|
62
|
-
| `6` | Budget overflow | Inform the user that the scoped context exceeds the token budget. Suggest narrowing scope with `--max-components` or `--budget`. **Stop.** |
|
|
81
|
+
When `/docs` does not exist, the repository has no established documentation. The skill investigates the codebase directly before conducting the interview.
|
|
63
82
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
83
|
+
### Process
|
|
84
|
+
|
|
85
|
+
1. **Investigate the codebase:** Read manifest files (`package.json`, `pyproject.toml`, `go.mod`, or equivalent), the directory structure, the README, and any existing configuration to identify the technology stack, frameworks, and conventions in use.
|
|
86
|
+
2. **Present a findings summary:** Show the user what was found — stack, frameworks, notable directories, confidence per finding — before the interview.
|
|
87
|
+
3. **Conduct the interview:** Proceed with the standard clarifying questions for product and technical context (same as documented-repository mode).
|
|
88
|
+
4. **Generate documents:** Create `docs/product.md` and `docs/tech.md` using the investigation findings as pre-filled context combined with interview answers.
|
|
89
|
+
5. **Save Output:** Save both documents in `/docs/` and present them for user review.
|
|
68
90
|
|
|
69
91
|
### Constraints
|
|
70
92
|
|
|
71
|
-
- The
|
|
72
|
-
-
|
|
73
|
-
- The skill **MAY** ask follow-up questions to fill gaps not covered by the bundle (e.g., strategic goals, success metrics).
|
|
93
|
+
- The investigation findings inform but do not replace the interview — the user confirms and supplements.
|
|
94
|
+
- If the repository has no identifiable stack (an empty project), skip investigation and proceed directly to the interview (pure greenfield).
|
|
74
95
|
|
|
75
96
|
---
|
|
76
97
|
|
|
77
|
-
|
|
98
|
+
---
|
|
78
99
|
|
|
79
|
-
|
|
100
|
+
## Repository Shape Detection
|
|
80
101
|
|
|
81
|
-
|
|
102
|
+
Before the interview, detect the repository's **shape**. This is independent of the mode above: a documented repository can be either shape, and so can a greenfield one.
|
|
82
103
|
|
|
83
|
-
|
|
84
|
-
2. **Ask Clarifying Questions:** Gather information for both product context and technical guidelines in a single interview. Group questions by domain.
|
|
85
|
-
3. **Generate Product Context Document:** Create `product-context.md` using the structure below.
|
|
86
|
-
4. **Generate Technical Guidelines Document:** Create `technical-guidelines.md` using the structure below.
|
|
87
|
-
5. **Save Output:** Save both documents in `/docs/` and present them for user review.
|
|
104
|
+
Detect from these signals (FR-59):
|
|
88
105
|
|
|
89
|
-
|
|
106
|
+
| Signal | Read for |
|
|
107
|
+
| ----------------------------------------- | ------------------------------ |
|
|
108
|
+
| `pnpm-workspace.yaml` | Shape **and** the package list |
|
|
109
|
+
| `workspaces` in `package.json` | Shape **and** the package list |
|
|
110
|
+
| `turbo.json` | Shape only |
|
|
111
|
+
| `nx.json` | Shape only |
|
|
112
|
+
| `lerna.json` | Shape only |
|
|
113
|
+
| `[tool.uv.workspace]` in `pyproject.toml` | Shape only |
|
|
90
114
|
|
|
91
|
-
|
|
115
|
+
Any signal present → **monorepo**. No signal → **single-package**.
|
|
92
116
|
|
|
93
|
-
|
|
117
|
+
Only the first two are parsed for a package list. When a repository signals monorepo through one of the other four, ask the user which packages exist rather than guessing.
|
|
94
118
|
|
|
95
|
-
|
|
119
|
+
`core/distribution/workspace.ts` exports `detectWorkspace(repoRoot)`, which returns the shape, the signals found, and the packages. Use it rather than re-deriving the answer.
|
|
96
120
|
|
|
97
|
-
|
|
98
|
-
2. **Run extraction:** Invoke `dt extract all --interactive` to extract schema, OpenAPI, AsyncAPI, and component manifest from the codebase.
|
|
99
|
-
- The `--interactive` flag allows the user to confirm or skip ambiguous extractions.
|
|
100
|
-
- If interrupted, the skill **SHOULD** inform the user how to resume (`dt extract all --interactive` picks up where it left off).
|
|
101
|
-
3. **Present extraction report:** Show the user the results of extraction — what was found, confidence levels, any `unresolved` items.
|
|
102
|
-
4. **Conduct the interview:** Proceed with the standard clarifying questions for product context and technical guidelines (same as Mono-Repo mode).
|
|
103
|
-
5. **Generate documents:** Create `product-context.md` and `technical-guidelines.md` using the extraction results as pre-filled context combined with interview answers.
|
|
104
|
-
6. **Save Output:** Save both documents in `/docs/` and present them for user review.
|
|
121
|
+
### Package Map
|
|
105
122
|
|
|
106
|
-
|
|
123
|
+
Record the result in `docs/tech.md` as a **Package Map** section, one row per package:
|
|
124
|
+
|
|
125
|
+
```markdown
|
|
126
|
+
## Package Map
|
|
127
|
+
|
|
128
|
+
| Package | Path | Purpose | Owner | Canonical scripts | Bounded context |
|
|
129
|
+
| ---------- | ------------- | ------------------- | -------- | --------------------- | --------------- |
|
|
130
|
+
| @acme/core | packages/core | Shared domain logic | platform | lint, typecheck, test | Ordering |
|
|
131
|
+
```
|
|
107
132
|
|
|
108
|
-
|
|
109
|
-
|
|
133
|
+
Rules:
|
|
134
|
+
|
|
135
|
+
- A **single-package repository records exactly one row**, for the root, with path `.`. The table has the same shape in both cases, so a reader never has to work out which kind of repository they are looking at.
|
|
136
|
+
- **Purpose** and **Owner** come from the interview. Do not invent an owner; ask.
|
|
137
|
+
- **Canonical scripts** lists the scripts the package actually defines, in the order `lint`, `format:check`, `typecheck`, `test`, `test:unit`, `test:integration`, `test:e2e`, `audit`, `validate`. Absent scripts are omitted, not marked missing.
|
|
138
|
+
- **Bounded context** is filled **freeform at interview time** (`shared-understanding#D-45`). Ask: _"In one phrase, what part of the business or domain does this package own?"_ A freeform guess beats an empty column. Once `docs/domain/ubiquitous-language.md` defines a bounded context, that file is canonical: copy the name from its `## Bounded Context:` heading character for character, because `lint`'s glossary check matches the two exactly (`shared-understanding#D-69`, closing `#D-45`).
|
|
139
|
+
- A package whose `package.json` has no `name` is listed by its path. Do not invent a name — nothing would match it.
|
|
140
|
+
|
|
141
|
+
`dev-tasks doctor` warns when the map and the workspace disagree in either direction: a package on disk with no row, or a row for a package that no longer exists. It warns and never fails; structural failures belong to `lint`.
|
|
110
142
|
|
|
111
143
|
---
|
|
112
144
|
|
|
145
|
+
### Runbooks
|
|
146
|
+
|
|
147
|
+
Initialization also establishes `docs/runbooks/` (PRD AC-26, S-005 AC-7). Create:
|
|
148
|
+
|
|
149
|
+
- `docs/runbooks/README.md` — the index, with Runbook / Trigger / Owner / Last verified columns.
|
|
150
|
+
- `docs/runbooks/runbook-template.md` — the form to copy for a new procedure.
|
|
151
|
+
|
|
152
|
+
`dev-tasks install` delivers both install-if-absent, so in an installed repository they are already present and **MUST NOT** be overwritten. Create them only when absent, and confirm with the user which procedures are worth a runbook now rather than writing placeholder files.
|
|
153
|
+
|
|
154
|
+
## SIMPLICITY.md Confirmation
|
|
155
|
+
|
|
156
|
+
`SIMPLICITY.md` ships at the repository root and states the code-simplicity contract, including section D's tool-enforced thresholds. During initialization you **MUST** confirm two things with the user rather than assuming them:
|
|
157
|
+
|
|
158
|
+
1. **Owner** — who is accountable for the contract. The shipped default is `housekeeping`.
|
|
159
|
+
2. **Thresholds** — section D's defaults (function length ≤ 40 lines, cyclomatic complexity ≤ 10, cognitive complexity ≤ 15, nesting depth ≤ 3, parameters ≤ 4, file length ≤ 400 lines). A repository **MAY** tighten a default; it **MUST NOT** loosen one.
|
|
160
|
+
|
|
161
|
+
Ask: _"SIMPLICITY.md's owner is `housekeeping` and its thresholds are the shipped defaults. Keep both, or tighten anything?"_ Record the answer in the file's frontmatter and in the section D table. Wiring the thresholds into a linter is a separate procedure — see `docs/runbooks/runbook-setup-simplicity-tooling.md`.
|
|
162
|
+
|
|
113
163
|
## Part 1 — Product Context
|
|
114
164
|
|
|
115
165
|
### Clarifying Questions
|
|
116
166
|
|
|
117
|
-
Adapt questions based on context
|
|
167
|
+
Adapt questions based on context already gathered (e.g., from codebase investigation in greenfield mode):
|
|
118
168
|
|
|
119
169
|
- **Product Definition:** "What is this product/project, and what does it do?"
|
|
120
170
|
- **Problem Statement:** "What core problem does this product solve?"
|
|
@@ -127,7 +177,7 @@ Adapt questions based on context provided (and based on mode — in multi-repo m
|
|
|
127
177
|
- **Key Constraints:** "Budget, timeline, technology, or regulatory constraints?"
|
|
128
178
|
- **Stakeholders:** "Who are the key decision-makers?"
|
|
129
179
|
|
|
130
|
-
### Output Structure: `product
|
|
180
|
+
### Output Structure: `docs/product.md`
|
|
131
181
|
|
|
132
182
|
0. **Changelog** — Version history table (see Document Changelog Convention above)
|
|
133
183
|
1. **Executive Summary** — 2-3 sentence overview
|
|
@@ -166,27 +216,28 @@ Adapt questions based on context provided (and based on mode — in multi-repo m
|
|
|
166
216
|
- **Package Manager Standard:** "Can we standardize on `pnpm` for JS/TS projects?"
|
|
167
217
|
- **Script Naming Standard:** "Should canonical `package.json` scripts (`lint`, `format:check`, `typecheck`, `test`, `audit`, `validate`) be enforced?"
|
|
168
218
|
|
|
169
|
-
### Output Structure: `
|
|
219
|
+
### Output Structure: `docs/tech.md`
|
|
170
220
|
|
|
171
221
|
0. **Changelog** — Version history table (see Document Changelog Convention above)
|
|
172
222
|
1. **Overview** — Technical vision and guiding principles
|
|
173
|
-
2. **
|
|
174
|
-
3. **
|
|
175
|
-
4. **
|
|
176
|
-
5. **
|
|
177
|
-
6. **
|
|
178
|
-
7. **
|
|
179
|
-
8. **
|
|
180
|
-
9. **
|
|
181
|
-
10. **
|
|
182
|
-
11. **
|
|
183
|
-
12. **
|
|
184
|
-
13. **
|
|
185
|
-
14. **
|
|
186
|
-
15. **
|
|
187
|
-
16. **
|
|
188
|
-
17. **
|
|
189
|
-
18. **
|
|
223
|
+
2. **Package Map** — Repository shape and one row per package (see Repository Shape Detection above)
|
|
224
|
+
3. **Technology Stack** — Backend/frontend languages, frameworks, databases, key dependencies
|
|
225
|
+
4. **Architecture Patterns** — System architecture, key decisions and rationale, component organization
|
|
226
|
+
5. **API Design Standards** — Style, naming, request/response formats, error handling
|
|
227
|
+
6. **Authentication & Authorization** — Mechanism, model, permission levels, session management
|
|
228
|
+
7. **Security Requirements** — Encryption, OWASP compliance, API key management, PII handling
|
|
229
|
+
8. **Data & Database Guidelines** — Schema patterns, naming conventions, query optimization, backup
|
|
230
|
+
9. **Integration Methods** — External integrations, patterns, retry/failure handling
|
|
231
|
+
10. **Code Organization & Structure** — Folder/file conventions, module boundaries, naming
|
|
232
|
+
11. **Design Patterns & Principles** — Preferred patterns, SOLID, DRY/KISS/YAGNI
|
|
233
|
+
12. **Testing Strategy** — Frameworks, testing pyramid, coverage, mock strategies
|
|
234
|
+
13. **Code Quality & Standards** — Linting, static analysis, reviews, documentation
|
|
235
|
+
14. **Deployment & DevOps** — Environments, CI/CD, infrastructure-as-code, containers
|
|
236
|
+
15. **Monitoring, Logging & Observability** — Levels, frameworks, alerting, error tracking
|
|
237
|
+
16. **Performance & Scalability** — Response targets, throughput, caching, optimization
|
|
238
|
+
17. **Dependency Management** — Management approach, version pinning, vulnerability scanning
|
|
239
|
+
18. **Development Workflow** — Branching strategy, commit conventions, PR process
|
|
240
|
+
19. **Known Constraints & Trade-offs** — Limitations and rationale
|
|
190
241
|
|
|
191
242
|
### JS/TS Package Manager and Script Defaults
|
|
192
243
|
|
|
@@ -208,7 +259,7 @@ When the project includes JavaScript/TypeScript:
|
|
|
208
259
|
|
|
209
260
|
- **Format:** Markdown (`.md`)
|
|
210
261
|
- **Location:** `/docs/`
|
|
211
|
-
- **Filenames:** `product
|
|
262
|
+
- **Filenames:** `product.md`, `tech.md`
|
|
212
263
|
|
|
213
264
|
## AGENTS.md Sizing
|
|
214
265
|
|
|
@@ -227,4 +278,3 @@ When generating or updating `AGENTS.md` during project initialization, you **MUS
|
|
|
227
278
|
5. You **MUST** save both files and present them for user review.
|
|
228
279
|
6. You **SHOULD** iterate based on user feedback before finalizing.
|
|
229
280
|
7. When updating an existing document, you **MUST** add a new row to the Changelog table with an incremented version, the current date, a summary of changes, and the responsible author/agent.
|
|
230
|
-
8. In multi-repo mode, you **MUST NOT** read `/docs` or walk the repository directly — all context passes through `dt init`.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: activity-integration-test-implementation
|
|
3
|
+
description: "Author integration tests (Layer 2.5) against real databases — local via testcontainers/docker-compose/Supabase CLI, remote via testing environments. Covers migrations, RLS, pgTAP, fixtures, and fallback paths. Use when writing or backfilling integration tests."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Activity: Integration Test Implementation (Layer 2.5)
|
|
7
|
+
|
|
8
|
+
Author integration tests that exercise code against a real database. Layer 2.5 exists because mocking the data layer makes SQL errors, type mismatches, NULL handling, malformed joins, and RLS policies structurally invisible.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
> **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
|
|
13
|
+
|
|
14
|
+
## Goal
|
|
15
|
+
|
|
16
|
+
Produce integration tests that fail when the data layer is wrong. If the database is mocked, the test belongs at Layer 2, not here.
|
|
17
|
+
|
|
18
|
+
Consult `/TESTING.md` first. Its Layer 2.5 boundary governs; this skill supplies the method.
|
|
19
|
+
|
|
20
|
+
## Layer 2.5 Boundary
|
|
21
|
+
|
|
22
|
+
- **MUST** use a real database (Postgres, SQLite, etc.) — not a mock or in-memory fake.
|
|
23
|
+
- **MUST NOT** mock the data layer. If you mock `sql`, `prisma`, `drizzle`, or the ORM client, the test is Layer 2.
|
|
24
|
+
- **MUST NOT** assert on SQL text or internal query shape. Assert on persisted state or returned data.
|
|
25
|
+
- **MAY** mock third-party external services (payment gateways, email providers) at the HTTP boundary.
|
|
26
|
+
|
|
27
|
+
## Part 1 — Local Integration Environment Detection
|
|
28
|
+
|
|
29
|
+
Detect the easiest applicable local option. Prefer in this order:
|
|
30
|
+
|
|
31
|
+
### 1. Testcontainers (preferred for isolation)
|
|
32
|
+
|
|
33
|
+
- Look for `@testcontainers/postgresql` or equivalent in `package.json`/`pom.xml`/`Cargo.toml`.
|
|
34
|
+
- Requires Docker. Check: `docker info` succeeds.
|
|
35
|
+
- Each test suite gets an ephemeral container — full isolation, no cleanup conflicts.
|
|
36
|
+
|
|
37
|
+
### 2. Docker Compose
|
|
38
|
+
|
|
39
|
+
- Look for `docker-compose.yml` or `compose.yml` with a database service.
|
|
40
|
+
- Requires Docker. Shared instance across tests — needs explicit state reset.
|
|
41
|
+
|
|
42
|
+
### 3. Supabase Local CLI
|
|
43
|
+
|
|
44
|
+
- Look for `supabase/config.toml` or `.supabase/` directory.
|
|
45
|
+
- Check: `supabase status` succeeds.
|
|
46
|
+
- Provides real Postgres with auth, storage, and edge functions locally.
|
|
47
|
+
|
|
48
|
+
### 4. Fallback — No Local Environment
|
|
49
|
+
|
|
50
|
+
- If Docker is unavailable and Supabase CLI is not installed, report the limitation.
|
|
51
|
+
- Emit: `SKIPPED(no local database environment — Docker unavailable, Supabase CLI not installed)`.
|
|
52
|
+
- Recommend environment setup as a follow-up. Do not silently omit.
|
|
53
|
+
|
|
54
|
+
## Part 2 — Fixtures, Seeding, and Lifecycle
|
|
55
|
+
|
|
56
|
+
### Test isolation
|
|
57
|
+
|
|
58
|
+
- Each test **SHOULD** run in a transaction that rolls back on completion (preferred).
|
|
59
|
+
- Alternative: truncate affected tables in `beforeEach`/`afterEach`.
|
|
60
|
+
- Alternative for testcontainers: fresh container per suite (slower but fully isolated).
|
|
61
|
+
|
|
62
|
+
### Seeding
|
|
63
|
+
|
|
64
|
+
- Shared seed data lives in one location per package (e.g., `test/fixtures/seed.sql` or `test/helpers/seed.ts`).
|
|
65
|
+
- Seeds **MUST** be idempotent — running twice produces the same state.
|
|
66
|
+
- Seeds **MUST NOT** depend on auto-increment IDs. Use deterministic UUIDs or named references.
|
|
67
|
+
|
|
68
|
+
### Deterministic teardown
|
|
69
|
+
|
|
70
|
+
- Every integration test file **MUST** clean up after itself or use rollback isolation.
|
|
71
|
+
- Tests **MUST NOT** depend on execution order.
|
|
72
|
+
- Tests **MUST NOT** leave residual data that affects other test files.
|
|
73
|
+
|
|
74
|
+
## Part 3 — Migration Clean-Apply Tests
|
|
75
|
+
|
|
76
|
+
- **MUST** test that all migrations apply cleanly from an empty database.
|
|
77
|
+
- **MUST** verify apply order (no duplicate prefixes, no gaps).
|
|
78
|
+
- **MUST** verify idempotency: running migrations twice does not error.
|
|
79
|
+
- For large stacks (50+ migrations): run full clean-apply on CI/scheduled; run latest N on PR.
|
|
80
|
+
- Report duplicate migration prefixes as a finding.
|
|
81
|
+
|
|
82
|
+
## Part 4 — Row-Level Security (RLS) Policy Tests
|
|
83
|
+
|
|
84
|
+
RLS tests **MUST** exercise the real database policy, not application-level tenant checks in JavaScript.
|
|
85
|
+
|
|
86
|
+
### Multi-session setup
|
|
87
|
+
|
|
88
|
+
- Create at least two database roles or authenticated sessions (Tenant A, Tenant B).
|
|
89
|
+
- Use `SET ROLE` or separate connections per tenant.
|
|
90
|
+
- For Supabase: use `supabase.auth.admin.createUser()` for test users, then authenticate with their JWTs.
|
|
91
|
+
|
|
92
|
+
### Required assertions
|
|
93
|
+
|
|
94
|
+
| Case | Assertion |
|
|
95
|
+
| ---------------------------- | ----------------------------------- |
|
|
96
|
+
| Tenant A reads own data | Returns expected rows |
|
|
97
|
+
| Tenant A reads Tenant B data | Returns empty set or error |
|
|
98
|
+
| Tenant A writes to Tenant B | Insert/update fails or is invisible |
|
|
99
|
+
| Unauthenticated access | Denied by policy |
|
|
100
|
+
| Service role bypasses RLS | Returns all rows (when expected) |
|
|
101
|
+
|
|
102
|
+
### Record limitations
|
|
103
|
+
|
|
104
|
+
If isolation is asserted against application-level checks rather than the real RLS policy, you **MUST** record: "Production RLS policy unverified — tested against application-layer tenant filtering only."
|
|
105
|
+
|
|
106
|
+
## Part 5 — pgTAP / Schema Contract Tests
|
|
107
|
+
|
|
108
|
+
Use pgTAP (or equivalent: `pg_prove`, raw SQL assertions) for:
|
|
109
|
+
|
|
110
|
+
- Table and column existence.
|
|
111
|
+
- Constraint verification (NOT NULL, UNIQUE, CHECK, FK).
|
|
112
|
+
- Function and trigger existence and signatures.
|
|
113
|
+
- Permission grants per role.
|
|
114
|
+
- Index existence for query-critical paths.
|
|
115
|
+
|
|
116
|
+
When pgTAP is unavailable, use raw `SELECT` assertions against `information_schema` or `pg_catalog`.
|
|
117
|
+
|
|
118
|
+
## Part 6 — Remote Integration Testing
|
|
119
|
+
|
|
120
|
+
### Default: read-only
|
|
121
|
+
|
|
122
|
+
- Inspect schema, permissions, RLS policies, and data shape without mutation.
|
|
123
|
+
- Use `EXPLAIN` for query plan verification without executing writes.
|
|
124
|
+
- No approval required for read-only operations.
|
|
125
|
+
|
|
126
|
+
### Testing environment writes
|
|
127
|
+
|
|
128
|
+
- **REQUIRE** explicit user approval before any write or migration apply.
|
|
129
|
+
- Connect only to a dedicated testing environment — never to production for writes.
|
|
130
|
+
- After writes: verify applied state, then clean up test data.
|
|
131
|
+
- Record: environment name, operation performed, approval evidence.
|
|
132
|
+
|
|
133
|
+
### No testing environment available
|
|
134
|
+
|
|
135
|
+
- Report: "Remote integration limited to read-only inspection. No testing environment configured."
|
|
136
|
+
- Recommend environment setup. Do not fabricate a pass.
|
|
137
|
+
|
|
138
|
+
## Output
|
|
139
|
+
|
|
140
|
+
- Tests written or updated, by path and layer
|
|
141
|
+
- Local environment detection result (which option selected, or fallback triggered)
|
|
142
|
+
- Migration clean-apply result
|
|
143
|
+
- RLS policy test coverage per table with RLS enabled
|
|
144
|
+
- Schema contract coverage (tables, constraints, functions)
|
|
145
|
+
- Remote integration status (read-only / testing-env / unavailable)
|
|
146
|
+
- Stated limitations where real-policy testing was not possible
|
|
147
|
+
|
|
148
|
+
## Final Instructions
|
|
149
|
+
|
|
150
|
+
1. You **MUST** consult `/TESTING.md` and respect its Layer 2.5 boundary.
|
|
151
|
+
2. You **MUST NOT** mock the data layer. If the database is mocked, the test is Layer 2.
|
|
152
|
+
3. You **MUST** detect the local environment and recommend the easiest applicable option.
|
|
153
|
+
4. You **MUST** report a limitation when no local or remote environment is available.
|
|
154
|
+
5. You **MUST** test RLS against the real policy layer, not application-level checks.
|
|
155
|
+
6. You **MUST** require explicit approval before any remote write operation.
|
|
156
|
+
7. You **MUST NOT** install dependencies — detect and recommend only.
|