@sienklogic/plan-build-run 2.53.0 → 2.55.0

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.
Files changed (165) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/package.json +2 -2
  3. package/plugins/codex-pbr/agents/audit.md +223 -0
  4. package/plugins/codex-pbr/agents/codebase-mapper.md +196 -0
  5. package/plugins/codex-pbr/agents/debugger.md +245 -0
  6. package/plugins/codex-pbr/agents/dev-sync.md +142 -0
  7. package/plugins/codex-pbr/agents/executor.md +429 -0
  8. package/plugins/codex-pbr/agents/general.md +131 -0
  9. package/plugins/codex-pbr/agents/integration-checker.md +178 -0
  10. package/plugins/codex-pbr/agents/plan-checker.md +253 -0
  11. package/plugins/codex-pbr/agents/planner.md +343 -0
  12. package/plugins/codex-pbr/agents/researcher.md +253 -0
  13. package/plugins/codex-pbr/agents/synthesizer.md +183 -0
  14. package/plugins/codex-pbr/agents/verifier.md +352 -0
  15. package/plugins/codex-pbr/commands/audit.md +5 -0
  16. package/plugins/codex-pbr/commands/begin.md +5 -0
  17. package/plugins/codex-pbr/commands/build.md +5 -0
  18. package/plugins/codex-pbr/commands/config.md +5 -0
  19. package/plugins/codex-pbr/commands/continue.md +5 -0
  20. package/plugins/codex-pbr/commands/dashboard.md +5 -0
  21. package/plugins/codex-pbr/commands/debug.md +5 -0
  22. package/plugins/codex-pbr/commands/discuss.md +5 -0
  23. package/plugins/codex-pbr/commands/do.md +5 -0
  24. package/plugins/codex-pbr/commands/explore.md +5 -0
  25. package/plugins/codex-pbr/commands/health.md +5 -0
  26. package/plugins/codex-pbr/commands/help.md +5 -0
  27. package/plugins/codex-pbr/commands/import.md +5 -0
  28. package/plugins/codex-pbr/commands/milestone.md +5 -0
  29. package/plugins/codex-pbr/commands/note.md +5 -0
  30. package/plugins/codex-pbr/commands/pause.md +5 -0
  31. package/plugins/codex-pbr/commands/plan.md +5 -0
  32. package/plugins/codex-pbr/commands/quick.md +5 -0
  33. package/plugins/codex-pbr/commands/resume.md +5 -0
  34. package/plugins/codex-pbr/commands/review.md +5 -0
  35. package/plugins/codex-pbr/commands/scan.md +5 -0
  36. package/plugins/codex-pbr/commands/setup.md +5 -0
  37. package/plugins/codex-pbr/commands/status.md +5 -0
  38. package/plugins/codex-pbr/commands/statusline.md +5 -0
  39. package/plugins/codex-pbr/commands/test.md +5 -0
  40. package/plugins/codex-pbr/commands/todo.md +5 -0
  41. package/plugins/codex-pbr/commands/undo.md +5 -0
  42. package/plugins/codex-pbr/references/agent-contracts.md +324 -0
  43. package/plugins/codex-pbr/references/agent-teams.md +54 -0
  44. package/plugins/codex-pbr/references/common-bug-patterns.md +13 -0
  45. package/plugins/codex-pbr/references/config-reference.md +552 -0
  46. package/plugins/codex-pbr/references/continuation-format.md +212 -0
  47. package/plugins/codex-pbr/references/deviation-rules.md +112 -0
  48. package/plugins/codex-pbr/references/git-integration.md +256 -0
  49. package/plugins/codex-pbr/references/integration-patterns.md +117 -0
  50. package/plugins/codex-pbr/references/model-profiles.md +99 -0
  51. package/plugins/codex-pbr/references/model-selection.md +31 -0
  52. package/plugins/codex-pbr/references/pbr-tools-cli.md +400 -0
  53. package/plugins/codex-pbr/references/plan-authoring.md +246 -0
  54. package/plugins/codex-pbr/references/plan-format.md +313 -0
  55. package/plugins/codex-pbr/references/questioning.md +235 -0
  56. package/plugins/codex-pbr/references/reading-verification.md +127 -0
  57. package/plugins/codex-pbr/references/signal-files.md +41 -0
  58. package/plugins/codex-pbr/references/stub-patterns.md +160 -0
  59. package/plugins/codex-pbr/references/ui-formatting.md +444 -0
  60. package/plugins/codex-pbr/references/wave-execution.md +95 -0
  61. package/plugins/codex-pbr/skills/audit/SKILL.md +346 -0
  62. package/plugins/codex-pbr/skills/begin/SKILL.md +800 -0
  63. package/plugins/codex-pbr/skills/build/SKILL.md +958 -0
  64. package/plugins/codex-pbr/skills/config/SKILL.md +267 -0
  65. package/plugins/codex-pbr/skills/continue/SKILL.md +172 -0
  66. package/plugins/codex-pbr/skills/dashboard/SKILL.md +44 -0
  67. package/plugins/codex-pbr/skills/debug/SKILL.md +530 -0
  68. package/plugins/codex-pbr/skills/discuss/SKILL.md +355 -0
  69. package/plugins/codex-pbr/skills/do/SKILL.md +68 -0
  70. package/plugins/codex-pbr/skills/explore/SKILL.md +407 -0
  71. package/plugins/codex-pbr/skills/health/SKILL.md +300 -0
  72. package/plugins/codex-pbr/skills/help/SKILL.md +229 -0
  73. package/plugins/codex-pbr/skills/import/SKILL.md +538 -0
  74. package/plugins/codex-pbr/skills/milestone/SKILL.md +620 -0
  75. package/plugins/codex-pbr/skills/note/SKILL.md +215 -0
  76. package/plugins/codex-pbr/skills/pause/SKILL.md +258 -0
  77. package/plugins/codex-pbr/skills/plan/SKILL.md +650 -0
  78. package/plugins/codex-pbr/skills/quick/SKILL.md +417 -0
  79. package/plugins/codex-pbr/skills/resume/SKILL.md +403 -0
  80. package/plugins/codex-pbr/skills/review/SKILL.md +669 -0
  81. package/plugins/codex-pbr/skills/scan/SKILL.md +325 -0
  82. package/plugins/codex-pbr/skills/setup/SKILL.md +169 -0
  83. package/plugins/codex-pbr/skills/shared/commit-planning-docs.md +35 -0
  84. package/plugins/codex-pbr/skills/shared/config-loading.md +102 -0
  85. package/plugins/codex-pbr/skills/shared/context-budget.md +77 -0
  86. package/plugins/codex-pbr/skills/shared/context-loader-task.md +86 -0
  87. package/plugins/codex-pbr/skills/shared/digest-select.md +79 -0
  88. package/plugins/codex-pbr/skills/shared/domain-probes.md +125 -0
  89. package/plugins/codex-pbr/skills/shared/error-reporting.md +59 -0
  90. package/plugins/codex-pbr/skills/shared/gate-prompts.md +388 -0
  91. package/plugins/codex-pbr/skills/shared/phase-argument-parsing.md +45 -0
  92. package/plugins/codex-pbr/skills/shared/revision-loop.md +81 -0
  93. package/plugins/codex-pbr/skills/shared/state-update.md +169 -0
  94. package/plugins/codex-pbr/skills/shared/universal-anti-patterns.md +43 -0
  95. package/plugins/codex-pbr/skills/status/SKILL.md +449 -0
  96. package/plugins/codex-pbr/skills/statusline/SKILL.md +149 -0
  97. package/plugins/codex-pbr/skills/test/SKILL.md +210 -0
  98. package/plugins/codex-pbr/skills/todo/SKILL.md +281 -0
  99. package/plugins/codex-pbr/skills/undo/SKILL.md +172 -0
  100. package/plugins/codex-pbr/templates/CONTEXT.md.tmpl +52 -0
  101. package/plugins/codex-pbr/templates/INTEGRATION-REPORT.md.tmpl +167 -0
  102. package/plugins/codex-pbr/templates/RESEARCH-SUMMARY.md.tmpl +97 -0
  103. package/plugins/codex-pbr/templates/ROADMAP.md.tmpl +47 -0
  104. package/plugins/codex-pbr/templates/SUMMARY-complex.md.tmpl +95 -0
  105. package/plugins/codex-pbr/templates/SUMMARY-minimal.md.tmpl +48 -0
  106. package/plugins/codex-pbr/templates/SUMMARY.md.tmpl +81 -0
  107. package/plugins/codex-pbr/templates/VERIFICATION-DETAIL.md.tmpl +117 -0
  108. package/plugins/codex-pbr/templates/codebase/ARCHITECTURE.md.tmpl +98 -0
  109. package/plugins/codex-pbr/templates/codebase/CONCERNS.md.tmpl +93 -0
  110. package/plugins/codex-pbr/templates/codebase/CONVENTIONS.md.tmpl +104 -0
  111. package/plugins/codex-pbr/templates/codebase/INTEGRATIONS.md.tmpl +78 -0
  112. package/plugins/codex-pbr/templates/codebase/STACK.md.tmpl +78 -0
  113. package/plugins/codex-pbr/templates/codebase/STRUCTURE.md.tmpl +80 -0
  114. package/plugins/codex-pbr/templates/codebase/TESTING.md.tmpl +107 -0
  115. package/plugins/codex-pbr/templates/continue-here.md.tmpl +73 -0
  116. package/plugins/codex-pbr/templates/pr-body.md.tmpl +22 -0
  117. package/plugins/codex-pbr/templates/prompt-partials/phase-project-context.md.tmpl +37 -0
  118. package/plugins/codex-pbr/templates/research/ARCHITECTURE.md.tmpl +124 -0
  119. package/plugins/codex-pbr/templates/research/STACK.md.tmpl +71 -0
  120. package/plugins/codex-pbr/templates/research/SUMMARY.md.tmpl +112 -0
  121. package/plugins/codex-pbr/templates/research-outputs/phase-research.md.tmpl +81 -0
  122. package/plugins/codex-pbr/templates/research-outputs/project-research.md.tmpl +99 -0
  123. package/plugins/codex-pbr/templates/research-outputs/synthesis.md.tmpl +36 -0
  124. package/plugins/copilot-pbr/commands/setup.md +1 -1
  125. package/plugins/copilot-pbr/commands/undo.md +5 -0
  126. package/plugins/copilot-pbr/plugin.json +1 -1
  127. package/plugins/copilot-pbr/skills/begin/SKILL.md +170 -17
  128. package/plugins/copilot-pbr/skills/build/SKILL.md +73 -8
  129. package/plugins/copilot-pbr/skills/plan/SKILL.md +67 -17
  130. package/plugins/copilot-pbr/skills/review/SKILL.md +12 -1
  131. package/plugins/copilot-pbr/skills/setup/SKILL.md +66 -214
  132. package/plugins/copilot-pbr/skills/shared/context-budget.md +27 -0
  133. package/plugins/copilot-pbr/skills/status/SKILL.md +44 -2
  134. package/plugins/copilot-pbr/skills/undo/SKILL.md +172 -0
  135. package/plugins/cursor-pbr/.cursor-plugin/plugin.json +1 -1
  136. package/plugins/cursor-pbr/commands/setup.md +1 -1
  137. package/plugins/cursor-pbr/commands/undo.md +5 -0
  138. package/plugins/cursor-pbr/skills/begin/SKILL.md +170 -17
  139. package/plugins/cursor-pbr/skills/build/SKILL.md +73 -8
  140. package/plugins/cursor-pbr/skills/plan/SKILL.md +67 -17
  141. package/plugins/cursor-pbr/skills/review/SKILL.md +12 -1
  142. package/plugins/cursor-pbr/skills/setup/SKILL.md +66 -214
  143. package/plugins/cursor-pbr/skills/shared/context-budget.md +27 -0
  144. package/plugins/cursor-pbr/skills/status/SKILL.md +44 -2
  145. package/plugins/cursor-pbr/skills/undo/SKILL.md +173 -0
  146. package/plugins/jules-pbr/AGENTS.md +600 -0
  147. package/plugins/pbr/.claude-plugin/plugin.json +1 -1
  148. package/plugins/pbr/commands/setup.md +1 -1
  149. package/plugins/pbr/commands/undo.md +5 -0
  150. package/plugins/pbr/scripts/config-schema.json +5 -1
  151. package/plugins/pbr/scripts/lib/alternatives.js +203 -0
  152. package/plugins/pbr/scripts/lib/preview.js +174 -0
  153. package/plugins/pbr/scripts/lib/skill-section.js +99 -0
  154. package/plugins/pbr/scripts/lib/step-verify.js +149 -0
  155. package/plugins/pbr/scripts/pbr-tools.js +122 -2
  156. package/plugins/pbr/scripts/validate-commit.js +2 -2
  157. package/plugins/pbr/skills/begin/SKILL.md +170 -17
  158. package/plugins/pbr/skills/begin/templates/config.json.tmpl +5 -1
  159. package/plugins/pbr/skills/build/SKILL.md +73 -8
  160. package/plugins/pbr/skills/plan/SKILL.md +67 -17
  161. package/plugins/pbr/skills/review/SKILL.md +12 -1
  162. package/plugins/pbr/skills/setup/SKILL.md +66 -214
  163. package/plugins/pbr/skills/shared/context-budget.md +27 -0
  164. package/plugins/pbr/skills/status/SKILL.md +44 -2
  165. package/plugins/pbr/skills/undo/SKILL.md +174 -0
@@ -0,0 +1,98 @@
1
+ <!-- Source: agents/codebase-mapper.md | Purpose: Output format for ARCHITECTURE.md codebase analysis -->
2
+ # Architecture
3
+
4
+ > Analyzed: {date}
5
+ > Pattern: {MVC / Layered / Hexagonal / Microservices / Monolith / etc.}
6
+
7
+ ## Pattern Overview
8
+
9
+ {2-3 paragraphs describing the overall architectural pattern with evidence from the codebase}
10
+
11
+ **Evidence**: {file paths, import patterns, directory structure that support this classification}
12
+
13
+ ## Layers
14
+
15
+ | Layer | Purpose | Directory | Key Files |
16
+ |-------|---------|-----------|-----------|
17
+ | {Presentation} | {UI rendering} | {src/components/} | {App.tsx, Layout.tsx} |
18
+ | {API/Routes} | {HTTP handling} | {src/routes/ or src/app/api/} | {users.ts, auth.ts} |
19
+ | {Business Logic} | {Core domain} | {src/services/} | {UserService.ts} |
20
+ | {Data Access} | {Database interaction} | {src/repositories/ or src/db/} | {UserRepo.ts} |
21
+ | {Infrastructure} | {External services} | {src/lib/ or src/integrations/} | {email.ts, storage.ts} |
22
+
23
+ ### Layer Rules
24
+
25
+ {How layers communicate — what imports what? What are the dependency rules?}
26
+
27
+ ```
28
+ Presentation → API → Business → Data Access → Database
29
+
30
+ Infrastructure
31
+ ```
32
+
33
+ ## Data Flow
34
+
35
+ ### Request Lifecycle
36
+
37
+ {How a typical request flows through the system}
38
+
39
+ ```
40
+ 1. Client sends request
41
+ 2. → {Router/Framework} routes to handler
42
+ 3. → {Middleware} runs (auth, validation, logging)
43
+ 4. → {Controller/Handler} processes request
44
+ 5. → {Service} executes business logic
45
+ 6. → {Repository/Model} queries database
46
+ 7. → Response returns through the stack
47
+ ```
48
+
49
+ ### State Management
50
+
51
+ | Context | Approach | Implementation | Files |
52
+ |---------|----------|---------------|-------|
53
+ | Client state | {Redux / Zustand / Context / etc.} | {how it's structured} | {store files} |
54
+ | Server state | {React Query / SWR / etc.} | {how it's used} | {hook files} |
55
+ | Session state | {JWT / cookies / etc.} | {how it's managed} | {auth files} |
56
+
57
+ ## Key Abstractions
58
+
59
+ | Abstraction | Purpose | Implementation | Used By |
60
+ |-------------|---------|---------------|---------|
61
+ | {Repository} | {Database access} | {Abstract class + implementations} | {Services} |
62
+ | {Middleware} | {Cross-cutting concerns} | {Function signature} | {Routes} |
63
+ | {DTO/Schema} | {Data validation} | {Zod schemas / class-validator} | {Routes, Services} |
64
+
65
+ ## Entry Points
66
+
67
+ | Type | File | Config | Notes |
68
+ |------|------|--------|-------|
69
+ | Web app | {src/app/page.tsx} | {port 3000} | {Next.js App Router} |
70
+ | API server | {src/server.ts} | {port 8080} | {Express server} |
71
+ | CLI | {src/cli.ts} | - | {Commander.js} |
72
+ | Workers | {src/workers/} | {queue config} | {Bull/BullMQ} |
73
+ | Cron | {src/cron/} | {schedule} | {node-cron} |
74
+
75
+ ## Error Handling Strategy
76
+
77
+ | Layer | Pattern | Implementation |
78
+ |-------|---------|---------------|
79
+ | API | {Error middleware + HTTP status codes} | {src/middleware/error.ts} |
80
+ | Service | {Custom error classes} | {src/errors/} |
81
+ | Client | {Error boundaries + toast notifications} | {src/components/ErrorBoundary.tsx} |
82
+
83
+ ### Error Flow
84
+
85
+ ```
86
+ Service throws AppError → Controller catches → Error middleware formats response → Client displays
87
+ ```
88
+
89
+ ## Security Architecture
90
+
91
+ | Aspect | Implementation | Files |
92
+ |--------|---------------|-------|
93
+ | Authentication | {how auth works} | {files} |
94
+ | Authorization | {RBAC / ABAC / etc.} | {files} |
95
+ | Input validation | {where and how} | {files} |
96
+ | CORS | {configuration} | {files} |
97
+ | Rate limiting | {if present} | {files} |
98
+ | CSRF protection | {if present} | {files} |
@@ -0,0 +1,93 @@
1
+ <!-- Source: agents/codebase-mapper.md | Purpose: Output format for CONCERNS.md codebase analysis -->
2
+ # Concerns & Technical Debt
3
+
4
+ > Analyzed: {date}
5
+ > Severity summary: {n critical, n high, n medium, n low}
6
+
7
+ ## Technical Debt
8
+
9
+ | # | Area | Issue | Severity | Files | Evidence |
10
+ |---|------|-------|----------|-------|----------|
11
+ | 1 | {area} | {what's wrong} | critical/high/medium/low | {file paths} | {what you saw} |
12
+ | 2 | {area} | {what's wrong} | {severity} | {file paths} | {what you saw} |
13
+
14
+ ### Debt Details
15
+
16
+ #### TD-1: {Issue Title}
17
+
18
+ **Severity**: {critical / high / medium / low}
19
+ **Files**: {list of affected files}
20
+ **Description**: {detailed description of the issue}
21
+ **Evidence**: {specific code examples, line numbers}
22
+ **Impact**: {what problems this causes or could cause}
23
+ **Recommendation**: {specific action to fix}
24
+
25
+ ## Known Bugs
26
+
27
+ | # | Description | Severity | Location | Reproduction |
28
+ |---|-------------|----------|----------|--------------|
29
+ | 1 | {bug description} | {severity} | {file:line} | {how to trigger} |
30
+
31
+ ## Security Considerations
32
+
33
+ | # | Issue | Severity | Location | Recommendation |
34
+ |---|-------|----------|----------|----------------|
35
+ | 1 | {Missing input validation on API} | high | {src/routes/users.ts} | {Add zod schema validation} |
36
+ | 2 | {Hardcoded secret in source} | critical | {src/config.ts:42} | {Move to environment variable} |
37
+ | 3 | {SQL injection risk} | critical | {src/db/queries.ts:15} | {Use parameterized queries} |
38
+ | 4 | {No rate limiting} | medium | {src/server.ts} | {Add express-rate-limit} |
39
+ | 5 | {No CSRF protection} | medium | {src/routes/} | {Add csrf tokens} |
40
+
41
+ ## Performance Risks
42
+
43
+ | # | Issue | Location | Impact | Recommendation |
44
+ |---|-------|----------|--------|----------------|
45
+ | 1 | {N+1 query in user list} | {src/routes/users.ts:30} | {Slow page load} | {Use eager loading} |
46
+ | 2 | {No pagination on large queries} | {src/routes/posts.ts:15} | {Memory exhaustion} | {Add cursor pagination} |
47
+ | 3 | {Synchronous file operations} | {src/utils/file.ts} | {Blocks event loop} | {Use async fs methods} |
48
+
49
+ ## Fragile Areas
50
+
51
+ | # | Area | Why Fragile | Impact of Breaking | Files |
52
+ |---|------|-------------|-------------------|-------|
53
+ | 1 | {Auth middleware} | {Tightly coupled to 5 services} | {All protected routes fail} | {files} |
54
+ | 2 | {Data migration} | {No rollback mechanism} | {Data loss on failure} | {files} |
55
+
56
+ ## Dependency Risks
57
+
58
+ | Package | Version | Issue | Recommendation |
59
+ |---------|---------|-------|----------------|
60
+ | {package} | {version} | {Deprecated / EOL / Known vulnerability} | {Update to X / Replace with Y} |
61
+
62
+ ## Scaling Limitations
63
+
64
+ | # | Limitation | When It Breaks | Current State | Fix Approach |
65
+ |---|-----------|---------------|---------------|-------------|
66
+ | 1 | {Single database instance} | {>1000 concurrent users} | {adequate for current load} | {Read replicas} |
67
+ | 2 | {In-memory session store} | {Multiple server instances} | {single instance} | {Redis session store} |
68
+
69
+ ## Missing Infrastructure
70
+
71
+ | Category | Status | Impact | Priority |
72
+ |----------|--------|--------|----------|
73
+ | Error monitoring | {absent/partial/present} | {bugs go unnoticed} | {high} |
74
+ | Logging | {absent/partial/present} | {hard to debug production} | {high} |
75
+ | CI/CD | {absent/partial/present} | {manual deployments} | {medium} |
76
+ | Automated tests | {absent/partial/present} | {regressions not caught} | {high} |
77
+ | Documentation | {absent/partial/present} | {onboarding difficulty} | {low} |
78
+ | Backup/Recovery | {absent/partial/present} | {data loss risk} | {critical} |
79
+ | Health checks | {absent/partial/present} | {outages not detected} | {medium} |
80
+
81
+ ## Recommendations (Prioritized)
82
+
83
+ ### Critical (Fix Immediately)
84
+ 1. {Recommendation with specific action}
85
+
86
+ ### High (Fix Soon)
87
+ 1. {Recommendation with specific action}
88
+
89
+ ### Medium (Plan to Fix)
90
+ 1. {Recommendation with specific action}
91
+
92
+ ### Low (When Convenient)
93
+ 1. {Recommendation with specific action}
@@ -0,0 +1,104 @@
1
+ <!-- Source: agents/codebase-mapper.md | Purpose: Output format for CONVENTIONS.md codebase analysis -->
2
+ # Code Conventions
3
+
4
+ > Analyzed: {date}
5
+ > Based on: {n} files inspected
6
+
7
+ ## Naming Conventions
8
+
9
+ | Entity | Convention | Example |
10
+ |--------|-----------|---------|
11
+ | Files (components) | {PascalCase.tsx} | `UserProfile.tsx` |
12
+ | Files (utilities) | {camelCase.ts} | `formatDate.ts` |
13
+ | Functions | {camelCase} | `getUserById` |
14
+ | Classes | {PascalCase} | `UserService` |
15
+ | Interfaces | {PascalCase, no I prefix} | `UserProfile` |
16
+ | Types | {PascalCase} | `CreateUserInput` |
17
+ | Constants | {SCREAMING_SNAKE_CASE or camelCase} | `MAX_RETRIES` or `maxRetries` |
18
+ | Enum members | {PascalCase} | `UserRole.Admin` |
19
+ | Environment variables | {SCREAMING_SNAKE_CASE} | `DATABASE_URL` |
20
+ | CSS classes | {kebab-case or camelCase modules} | `user-profile` |
21
+ | Database tables | {snake_case} | `user_profiles` |
22
+ | API endpoints | {kebab-case} | `/api/user-profiles` |
23
+
24
+ ## Code Style
25
+
26
+ | Aspect | Setting | Config File |
27
+ |--------|---------|-------------|
28
+ | Indentation | {2 spaces / 4 spaces / tabs} | {.editorconfig / .prettierrc} |
29
+ | Quotes | {single / double} | {.prettierrc} |
30
+ | Semicolons | {yes / no} | {.prettierrc} |
31
+ | Trailing commas | {all / es5 / none} | {.prettierrc} |
32
+ | Line width | {80 / 100 / 120} | {.prettierrc} |
33
+ | Line endings | {LF / CRLF} | {.editorconfig} |
34
+
35
+ ## Import Organization
36
+
37
+ {Observed import order pattern from the codebase}
38
+
39
+ ```{language}
40
+ // 1. Node.js built-in modules
41
+ import path from 'path';
42
+
43
+ // 2. External packages
44
+ import React from 'react';
45
+ import { z } from 'zod';
46
+
47
+ // 3. Internal aliases
48
+ import { Button } from '@/components/ui';
49
+ import { useAuth } from '@/hooks/useAuth';
50
+
51
+ // 4. Relative imports
52
+ import { UserCard } from './UserCard';
53
+ import type { User } from './types';
54
+
55
+ // 5. Style imports
56
+ import styles from './UserProfile.module.css';
57
+ ```
58
+
59
+ ## Function Patterns
60
+
61
+ ### Async Functions
62
+
63
+ ```{language}
64
+ // Pattern used in this codebase: {evidence file:line}
65
+ {actual code pattern from codebase}
66
+ ```
67
+
68
+ ### Error Handling
69
+
70
+ ```{language}
71
+ // Pattern used in this codebase: {evidence file:line}
72
+ {actual code pattern from codebase}
73
+ ```
74
+
75
+ ### API Route Handlers
76
+
77
+ ```{language}
78
+ // Pattern used in this codebase: {evidence file:line}
79
+ {actual code pattern from codebase}
80
+ ```
81
+
82
+ ### React Components
83
+
84
+ ```{language}
85
+ // Pattern used in this codebase: {evidence file:line}
86
+ {actual code pattern from codebase}
87
+ ```
88
+
89
+ ## Comment Conventions
90
+
91
+ | When | Style | Example |
92
+ |------|-------|---------|
93
+ | {Complex logic} | {inline comment} | `// Calculate tax with progressive rates` |
94
+ | {Public API} | {JSDoc} | `/** @param user - The user to validate */` |
95
+ | {Temporary} | {TODO with ticket} | `// TODO(#123): refactor after migration` |
96
+ | {Warning} | {IMPORTANT prefix} | `// IMPORTANT: this must run before auth` |
97
+
98
+ ## Git Conventions
99
+
100
+ | Aspect | Convention | Example |
101
+ |--------|-----------|---------|
102
+ | Branch naming | {pattern} | `feature/add-user-auth` |
103
+ | Commit format | {conventional commits / custom} | `feat(auth): add login flow` |
104
+ | PR titles | {pattern} | `[Feature] Add user authentication` |
@@ -0,0 +1,78 @@
1
+ <!-- Source: agents/codebase-mapper.md | Purpose: Output format for INTEGRATIONS.md codebase analysis -->
2
+ # External Integrations
3
+
4
+ > Analyzed: {date}
5
+ > Total integrations: {n}
6
+
7
+ ## APIs
8
+
9
+ | Service | Type | Auth Method | Config Var | Used In | Documentation |
10
+ |---------|------|-------------|------------|---------|---------------|
11
+ | {Discord API} | REST | {OAuth2} | DISCORD_TOKEN | {src/integrations/discord.ts} | {URL} |
12
+ | {Stripe} | REST | {API Key} | STRIPE_SECRET_KEY | {src/payments/} | {URL} |
13
+
14
+ ### API Client Patterns
15
+
16
+ {How API calls are made in this codebase — fetch wrapper? axios instance? SDK?}
17
+
18
+ ```{language}
19
+ // Example from codebase: {file:line}
20
+ {actual code pattern}
21
+ ```
22
+
23
+ ## Databases
24
+
25
+ | Database | Type | ORM/Driver | Config | Schema Location | Migrations |
26
+ |----------|------|-----------|--------|-----------------|------------|
27
+ | {PostgreSQL} | {Relational} | {Prisma} | DATABASE_URL | {prisma/schema.prisma} | {prisma/migrations/} |
28
+ | {Redis} | {Key-value} | {ioredis} | REDIS_URL | - | - |
29
+
30
+ ### Database Patterns
31
+
32
+ {How database access is structured — repository pattern? direct queries? ORM models?}
33
+
34
+ ## Authentication & Authorization
35
+
36
+ | Aspect | Implementation | Config | Files |
37
+ |--------|---------------|--------|-------|
38
+ | Method | {JWT / Session / OAuth} | {env vars} | {files} |
39
+ | Provider | {self / Auth0 / Clerk / etc.} | {env vars} | {files} |
40
+ | Storage | {cookie / localStorage / header} | - | {files} |
41
+ | Roles | {admin, user, etc.} | {where defined} | {files} |
42
+
43
+ ## Email/Notifications
44
+
45
+ | Service | Purpose | Config | Used In |
46
+ |---------|---------|--------|---------|
47
+ | {SendGrid} | {Transactional email} | SENDGRID_KEY | {src/email/} |
48
+
49
+ ## File Storage
50
+
51
+ | Service | Purpose | Config | Used In |
52
+ |---------|---------|--------|---------|
53
+ | {S3} | {User uploads} | AWS_* vars | {src/storage/} |
54
+
55
+ ## Monitoring & Logging
56
+
57
+ | Tool | Purpose | Config | Used In |
58
+ |------|---------|--------|---------|
59
+ | {Sentry} | {Error tracking} | SENTRY_DSN | {src/lib/sentry.ts} |
60
+ | {Winston} | {Logging} | - | {src/lib/logger.ts} |
61
+
62
+ ## CI/CD
63
+
64
+ | Platform | Config | Stages | Deployment |
65
+ |----------|--------|--------|------------|
66
+ | {GitHub Actions} | {.github/workflows/} | {lint, test, build, deploy} | {Vercel / AWS / etc.} |
67
+
68
+ ### Pipeline Details
69
+
70
+ {Description of the CI/CD pipeline flow}
71
+
72
+ ## Infrastructure
73
+
74
+ | Component | Provider | Config | Notes |
75
+ |-----------|----------|--------|-------|
76
+ | {Hosting} | {Vercel} | {vercel.json} | {auto-deploy from main} |
77
+ | {DNS} | {Cloudflare} | - | {if relevant} |
78
+ | {CDN} | {included with host} | - | - |
@@ -0,0 +1,78 @@
1
+ <!-- Source: agents/codebase-mapper.md | Purpose: Output format for STACK.md codebase analysis -->
2
+ # Technology Stack
3
+
4
+ > Analyzed: {date}
5
+ > Project: {project name from package.json or directory}
6
+
7
+ ## Languages & Runtime
8
+
9
+ | Language | Version | Config | Notes |
10
+ |----------|---------|--------|-------|
11
+ | TypeScript | {version from tsconfig target or dep} | `tsconfig.json` | {strict mode? path aliases?} |
12
+ | Node.js | {version from engines or .nvmrc} | `.nvmrc` / `package.json engines` | {LTS?} |
13
+
14
+ ## Frameworks
15
+
16
+ | Framework | Version | Role | Entry Point | Config |
17
+ |-----------|---------|------|-------------|--------|
18
+ | {Next.js} | {14.x} | {Web framework} | {src/app/} | {next.config.js} |
19
+ | {Express} | {4.x} | {API server} | {src/server.ts} | - |
20
+
21
+ ## Key Dependencies
22
+
23
+ ### Production Dependencies
24
+
25
+ | Package | Version | Purpose | Used In |
26
+ |---------|---------|---------|---------|
27
+ | {prisma} | {5.x} | {ORM / database} | {src/db/} |
28
+ | {zod} | {3.x} | {Validation} | {src/validators/} |
29
+
30
+ ### Development Dependencies
31
+
32
+ | Package | Version | Purpose | Config |
33
+ |---------|---------|---------|--------|
34
+ | {jest} | {29.x} | {Testing} | {jest.config.ts} |
35
+ | {eslint} | {8.x} | {Linting} | {.eslintrc.js} |
36
+
37
+ ## Build & Tooling
38
+
39
+ | Tool | Config File | Purpose | Commands |
40
+ |------|-------------|---------|----------|
41
+ | {TypeScript} | `tsconfig.json` | {Compilation} | `npx tsc --noEmit` |
42
+ | {ESLint} | `.eslintrc.js` | {Linting} | `npm run lint` |
43
+ | {Prettier} | `.prettierrc` | {Formatting} | `npm run format` |
44
+ | {Jest} | `jest.config.ts` | {Testing} | `npm test` |
45
+
46
+ ## Package Manager
47
+
48
+ - **Manager**: {npm / yarn / pnpm / bun}
49
+ - **Lock file**: {package-lock.json / yarn.lock / pnpm-lock.yaml}
50
+ - **Workspaces**: {yes/no, if yes: list workspace paths}
51
+
52
+ ## Environment Configuration
53
+
54
+ | Variable | Required | Default | Purpose | Where Used |
55
+ |----------|----------|---------|---------|------------|
56
+ | DATABASE_URL | YES | - | Database connection | {src/db/} |
57
+ | {VAR_NAME} | {YES/NO} | {value} | {purpose} | {files} |
58
+
59
+ **Template**: {`.env.example` exists? Y/N}
60
+
61
+ ## Platform Requirements
62
+
63
+ | Requirement | Value | Source |
64
+ |------------|-------|--------|
65
+ | Node version | {>=18} | {package.json engines} |
66
+ | OS | {any / linux only / etc.} | {evidence} |
67
+ | Memory | {if specified} | {evidence} |
68
+ | External services | {list databases, caches, etc.} | {docker-compose, docs} |
69
+
70
+ ## Scripts
71
+
72
+ | Script | Command | Purpose |
73
+ |--------|---------|---------|
74
+ | `dev` | {command} | {Start dev server} |
75
+ | `build` | {command} | {Build for production} |
76
+ | `test` | {command} | {Run tests} |
77
+ | `lint` | {command} | {Run linter} |
78
+ | {others} | {command} | {purpose} |
@@ -0,0 +1,80 @@
1
+ <!-- Source: agents/codebase-mapper.md | Purpose: Output format for STRUCTURE.md codebase analysis -->
2
+ # Project Structure
3
+
4
+ > Analyzed: {date}
5
+
6
+ ## Directory Layout
7
+
8
+ ```
9
+ {project_root}/
10
+ ├── src/ # Source code
11
+ │ ├── app/ # {Purpose: Next.js App Router pages}
12
+ │ │ ├── api/ # {API route handlers}
13
+ │ │ ├── (auth)/ # {Auth-related pages}
14
+ │ │ └── layout.tsx # {Root layout}
15
+ │ ├── components/ # {Shared UI components}
16
+ │ │ ├── ui/ # {Primitive UI components}
17
+ │ │ └── features/ # {Feature-specific components}
18
+ │ ├── lib/ # {Shared utilities and configurations}
19
+ │ ├── services/ # {Business logic}
20
+ │ ├── models/ # {Data models / types}
21
+ │ ├── hooks/ # {Custom React hooks}
22
+ │ └── styles/ # {Global styles}
23
+ ├── prisma/ # {Database schema and migrations}
24
+ ├── public/ # {Static assets}
25
+ ├── tests/ # {Test files}
26
+ ├── docs/ # {Documentation}
27
+ └── scripts/ # {Build/deploy scripts}
28
+ ```
29
+
30
+ ## File Naming Conventions
31
+
32
+ | Type | Pattern | Example |
33
+ |------|---------|---------|
34
+ | React components | {PascalCase.tsx} | `UserProfile.tsx` |
35
+ | Hooks | {camelCase.ts, use* prefix} | `useAuth.ts` |
36
+ | Utilities | {camelCase.ts} | `formatDate.ts` |
37
+ | Types | {PascalCase.ts or types.ts} | `User.ts`, `types.ts` |
38
+ | Tests | {*.test.ts or *.spec.ts} | `UserProfile.test.tsx` |
39
+ | API routes | {route.ts in directory} | `app/api/users/route.ts` |
40
+ | Config | {lowercase with dots} | `jest.config.ts` |
41
+ | Constants | {UPPER_CASE or camelCase} | `constants.ts` |
42
+
43
+ ## Module Boundaries
44
+
45
+ {How the code is organized into modules/features and what the boundaries are}
46
+
47
+ | Module | Directory | Responsibility | Dependencies |
48
+ |--------|-----------|---------------|-------------|
49
+ | {Auth} | {src/auth/} | {Authentication & session} | {Database, Config} |
50
+ | {Users} | {src/users/} | {User CRUD} | {Auth, Database} |
51
+
52
+ ## Import Patterns
53
+
54
+ {How imports are organized in this codebase}
55
+
56
+ ```{language}
57
+ // Standard import order observed in this project:
58
+ // {example from actual codebase}
59
+ ```
60
+
61
+ ### Path Aliases
62
+
63
+ | Alias | Maps To | Config |
64
+ |-------|---------|--------|
65
+ | `@/` | `src/` | `tsconfig.json paths` |
66
+ | `@components/` | `src/components/` | `tsconfig.json paths` |
67
+
68
+ ## Where to Add Code
69
+
70
+ | Type of Code | Location | Convention | Example |
71
+ |-------------|----------|------------|---------|
72
+ | New API route | `src/app/api/{resource}/route.ts` | {pattern} | {example} |
73
+ | New component | `src/components/{feature}/` | {pattern} | {example} |
74
+ | New service | `src/services/` | {pattern} | {example} |
75
+ | New model | `src/models/` | {pattern} | {example} |
76
+ | New test | `{co-located or tests/}` | {pattern} | {example} |
77
+ | New utility | `src/lib/` or `src/utils/` | {pattern} | {example} |
78
+ | New hook | `src/hooks/` | {pattern} | {example} |
79
+ | New migration | `prisma/migrations/` | `npx prisma migrate dev` | - |
80
+ | New env var | `.env` + `.env.example` | {pattern} | {example} |
@@ -0,0 +1,107 @@
1
+ <!-- Source: agents/codebase-mapper.md | Purpose: Output format for TESTING.md codebase analysis -->
2
+ # Testing Infrastructure
3
+
4
+ > Analyzed: {date}
5
+ > Test files found: {n}
6
+ > Coverage: {percentage if configured}
7
+
8
+ ## Framework
9
+
10
+ | Aspect | Value | Config |
11
+ |--------|-------|--------|
12
+ | Test runner | {Jest / Vitest / pytest / etc.} | {config file path} |
13
+ | Assertion library | {built-in / chai / etc.} | - |
14
+ | Mocking | {jest.mock / vitest.mock / unittest.mock} | - |
15
+ | Coverage tool | {c8 / istanbul / coverage.py} | {config} |
16
+
17
+ ## Running Tests
18
+
19
+ ```bash
20
+ # All tests
21
+ {npm test}
22
+
23
+ # Specific file
24
+ {npm test -- path/to/file}
25
+
26
+ # Watch mode
27
+ {npm run test:watch}
28
+
29
+ # Coverage
30
+ {npm run test:coverage}
31
+
32
+ # Specific pattern
33
+ {npm test -- --grep "pattern"}
34
+ ```
35
+
36
+ ## Test Organization
37
+
38
+ | Aspect | Pattern | Example |
39
+ |--------|---------|---------|
40
+ | Location | {co-located / separate directory} | `src/auth/auth.test.ts` or `tests/auth.test.ts` |
41
+ | File naming | {.test.ts / .spec.ts / test_.py} | `UserService.test.ts` |
42
+ | Describe blocks | {module/function/feature} | `describe('UserService')` |
43
+ | Test naming | {should X / it X / test_X} | `it('should return user by id')` |
44
+
45
+ ## Test Structure Pattern
46
+
47
+ ```{language}
48
+ // Pattern used in this codebase: {evidence file:line}
49
+ {actual test structure from codebase}
50
+ ```
51
+
52
+ ## Mocking Patterns
53
+
54
+ ### External Services
55
+
56
+ ```{language}
57
+ // How external services are mocked: {evidence file:line}
58
+ {actual mock pattern from codebase}
59
+ ```
60
+
61
+ ### Database
62
+
63
+ ```{language}
64
+ // How database is mocked/seeded: {evidence file:line}
65
+ {actual pattern from codebase}
66
+ ```
67
+
68
+ ### API Calls
69
+
70
+ ```{language}
71
+ // How API calls are mocked: {evidence file:line}
72
+ {actual pattern from codebase}
73
+ ```
74
+
75
+ ## Fixtures & Test Data
76
+
77
+ | Type | Location | Pattern |
78
+ |------|----------|---------|
79
+ | {Factories} | {tests/factories/} | {createUser(), createPost()} |
80
+ | {Fixtures} | {tests/fixtures/} | {JSON files} |
81
+ | {Seeds} | {prisma/seed.ts} | {Prisma seed script} |
82
+
83
+ ## Coverage Configuration
84
+
85
+ | Setting | Value |
86
+ |---------|-------|
87
+ | Threshold | {if configured: line %, branch %, function %} |
88
+ | Include | {file patterns} |
89
+ | Exclude | {file patterns} |
90
+ | Reporter | {text / html / lcov} |
91
+
92
+ ## E2E Testing
93
+
94
+ | Aspect | Value | Config |
95
+ |--------|-------|--------|
96
+ | Framework | {Playwright / Cypress / none} | {config file} |
97
+ | Location | {e2e/ or tests/e2e/} | - |
98
+ | Base URL | {config} | - |
99
+
100
+ ## Testing Gaps
101
+
102
+ | Area | Has Tests | Notes |
103
+ |------|-----------|-------|
104
+ | {Unit tests} | {YES/NO/PARTIAL} | {coverage details} |
105
+ | {Integration tests} | {YES/NO/PARTIAL} | {coverage details} |
106
+ | {E2E tests} | {YES/NO/PARTIAL} | {coverage details} |
107
+ | {API tests} | {YES/NO/PARTIAL} | {coverage details} |