beth-copilot 1.0.18 → 1.1.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.
- package/CHANGELOG.md +41 -28
- package/README.md +87 -247
- package/bin/cli.js +158 -358
- package/dist/__tests__/smoke.test.d.ts +8 -0
- package/dist/__tests__/smoke.test.d.ts.map +1 -0
- package/dist/__tests__/smoke.test.js +49 -0
- package/dist/__tests__/smoke.test.js.map +1 -0
- package/dist/cli/commands/beads.e2e.test.d.ts +13 -0
- package/dist/cli/commands/beads.e2e.test.d.ts.map +1 -0
- package/dist/cli/commands/beads.e2e.test.js +526 -0
- package/dist/cli/commands/beads.e2e.test.js.map +1 -0
- package/dist/cli/commands/cli-edge-cases.e2e.test.d.ts +32 -0
- package/dist/cli/commands/cli-edge-cases.e2e.test.d.ts.map +1 -0
- package/dist/cli/commands/cli-edge-cases.e2e.test.js +162 -0
- package/dist/cli/commands/cli-edge-cases.e2e.test.js.map +1 -0
- package/dist/cli/commands/close.d.ts +89 -0
- package/dist/cli/commands/close.d.ts.map +1 -0
- package/dist/cli/commands/close.e2e.test.d.ts +27 -0
- package/dist/cli/commands/close.e2e.test.d.ts.map +1 -0
- package/dist/cli/commands/close.e2e.test.js +252 -0
- package/dist/cli/commands/close.e2e.test.js.map +1 -0
- package/dist/cli/commands/close.js +309 -0
- package/dist/cli/commands/close.js.map +1 -0
- package/dist/cli/commands/close.test.d.ts +15 -0
- package/dist/cli/commands/close.test.d.ts.map +1 -0
- package/dist/cli/commands/close.test.js +634 -0
- package/dist/cli/commands/close.test.js.map +1 -0
- package/dist/cli/commands/doctor.d.ts +23 -0
- package/dist/cli/commands/doctor.d.ts.map +1 -1
- package/dist/cli/commands/doctor.js +93 -0
- package/dist/cli/commands/doctor.js.map +1 -1
- package/dist/cli/commands/doctor.test.js +209 -0
- package/dist/cli/commands/doctor.test.js.map +1 -1
- package/dist/cli/commands/framework-isolation.test.d.ts +30 -0
- package/dist/cli/commands/framework-isolation.test.d.ts.map +1 -0
- package/dist/cli/commands/framework-isolation.test.js +119 -0
- package/dist/cli/commands/framework-isolation.test.js.map +1 -0
- package/dist/cli/commands/help.e2e.test.js +4 -4
- package/dist/cli/commands/help.e2e.test.js.map +1 -1
- package/dist/cli/commands/init-logic.e2e.test.d.ts +37 -0
- package/dist/cli/commands/init-logic.e2e.test.d.ts.map +1 -0
- package/dist/cli/commands/init-logic.e2e.test.js +305 -0
- package/dist/cli/commands/init-logic.e2e.test.js.map +1 -0
- package/dist/cli/commands/land.d.ts +142 -0
- package/dist/cli/commands/land.d.ts.map +1 -0
- package/dist/cli/commands/land.js +647 -0
- package/dist/cli/commands/land.js.map +1 -0
- package/dist/cli/commands/land.test.d.ts +20 -0
- package/dist/cli/commands/land.test.d.ts.map +1 -0
- package/dist/cli/commands/land.test.js +622 -0
- package/dist/cli/commands/land.test.js.map +1 -0
- package/dist/cli/commands/mcp.e2e.test.js +22 -29
- package/dist/cli/commands/mcp.e2e.test.js.map +1 -1
- package/dist/cli/commands/pipeline.e2e.test.js +20 -20
- package/dist/cli/commands/pipeline.e2e.test.js.map +1 -1
- package/dist/cli/commands/pre-push-guard.d.ts +84 -0
- package/dist/cli/commands/pre-push-guard.d.ts.map +1 -0
- package/dist/cli/commands/pre-push-guard.e2e.test.d.ts +24 -0
- package/dist/cli/commands/pre-push-guard.e2e.test.d.ts.map +1 -0
- package/dist/cli/commands/pre-push-guard.e2e.test.js +171 -0
- package/dist/cli/commands/pre-push-guard.e2e.test.js.map +1 -0
- package/dist/cli/commands/pre-push-guard.js +257 -0
- package/dist/cli/commands/pre-push-guard.js.map +1 -0
- package/dist/cli/commands/pre-push-guard.test.d.ts +15 -0
- package/dist/cli/commands/pre-push-guard.test.d.ts.map +1 -0
- package/dist/cli/commands/pre-push-guard.test.js +397 -0
- package/dist/cli/commands/pre-push-guard.test.js.map +1 -0
- package/dist/cli/commands/quickstart-expanded.e2e.test.d.ts +23 -0
- package/dist/cli/commands/quickstart-expanded.e2e.test.d.ts.map +1 -0
- package/dist/cli/commands/quickstart-expanded.e2e.test.js +179 -0
- package/dist/cli/commands/quickstart-expanded.e2e.test.js.map +1 -0
- package/dist/cli/commands/quickstart.d.ts.map +1 -1
- package/dist/cli/commands/quickstart.js +7 -23
- package/dist/cli/commands/quickstart.js.map +1 -1
- package/dist/cli/commands/quickstart.test.js +40 -67
- package/dist/cli/commands/quickstart.test.js.map +1 -1
- package/dist/core/agents/suite.test.js +4 -2
- package/dist/core/agents/suite.test.js.map +1 -1
- package/dist/core/agents/tools.test.js +5 -1
- package/dist/core/agents/tools.test.js.map +1 -1
- package/dist/index.d.ts +3 -10
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -10
- package/dist/index.js.map +1 -1
- package/package.json +15 -9
- package/sbom.json +2011 -819
- package/templates/.github/agents/beth.agent.md +220 -66
- package/templates/.github/agents/developer.agent.md +53 -90
- package/templates/.github/agents/product-manager.agent.md +15 -68
- package/templates/.github/agents/researcher.agent.md +20 -71
- package/templates/.github/agents/security-reviewer.agent.md +29 -81
- package/templates/.github/agents/tester.agent.md +40 -69
- package/templates/.github/agents/ux-designer.agent.md +20 -74
- package/templates/.github/copilot-instructions.md +217 -225
- package/templates/AGENTS.md +108 -20
- package/templates/mcp.json.example +0 -3
- package/dist/cli/commands/client-config.d.ts +0 -31
- package/dist/cli/commands/client-config.d.ts.map +0 -1
- package/dist/cli/commands/client-config.e2e.test.d.ts +0 -15
- package/dist/cli/commands/client-config.e2e.test.d.ts.map +0 -1
- package/dist/cli/commands/client-config.e2e.test.js +0 -556
- package/dist/cli/commands/client-config.e2e.test.js.map +0 -1
- package/dist/cli/commands/client-config.js +0 -73
- package/dist/cli/commands/client-config.js.map +0 -1
- package/dist/cli/commands/client-config.test.d.ts +0 -6
- package/dist/cli/commands/client-config.test.d.ts.map +0 -1
- package/dist/cli/commands/client-config.test.js +0 -133
- package/dist/cli/commands/client-config.test.js.map +0 -1
- package/dist/cli/commands/init-quickstart.e2e.test.d.ts +0 -11
- package/dist/cli/commands/init-quickstart.e2e.test.d.ts.map +0 -1
- package/dist/cli/commands/init-quickstart.e2e.test.js +0 -221
- package/dist/cli/commands/init-quickstart.e2e.test.js.map +0 -1
- package/dist/core/context.d.ts +0 -171
- package/dist/core/context.d.ts.map +0 -1
- package/dist/core/context.js +0 -353
- package/dist/core/context.js.map +0 -1
- package/dist/core/context.test.d.ts +0 -8
- package/dist/core/context.test.d.ts.map +0 -1
- package/dist/core/context.test.js +0 -253
- package/dist/core/context.test.js.map +0 -1
- package/dist/core/handoffs.d.ts +0 -151
- package/dist/core/handoffs.d.ts.map +0 -1
- package/dist/core/handoffs.js +0 -220
- package/dist/core/handoffs.js.map +0 -1
- package/dist/core/handoffs.test.d.ts +0 -8
- package/dist/core/handoffs.test.d.ts.map +0 -1
- package/dist/core/handoffs.test.js +0 -231
- package/dist/core/handoffs.test.js.map +0 -1
- package/dist/core/orchestrator.d.ts +0 -246
- package/dist/core/orchestrator.d.ts.map +0 -1
- package/dist/core/orchestrator.js +0 -514
- package/dist/core/orchestrator.js.map +0 -1
- package/dist/core/orchestrator.test.d.ts +0 -8
- package/dist/core/orchestrator.test.d.ts.map +0 -1
- package/dist/core/orchestrator.test.js +0 -517
- package/dist/core/orchestrator.test.js.map +0 -1
- package/dist/core/router.d.ts +0 -102
- package/dist/core/router.d.ts.map +0 -1
- package/dist/core/router.js +0 -178
- package/dist/core/router.js.map +0 -1
- package/dist/core/router.test.d.ts +0 -8
- package/dist/core/router.test.d.ts.map +0 -1
- package/dist/core/router.test.js +0 -215
- package/dist/core/router.test.js.map +0 -1
- package/dist/init.test.js +0 -288
- package/dist/providers/azure.d.ts +0 -147
- package/dist/providers/azure.d.ts.map +0 -1
- package/dist/providers/azure.js +0 -491
- package/dist/providers/azure.js.map +0 -1
- package/dist/providers/azure.test.d.ts +0 -11
- package/dist/providers/azure.test.d.ts.map +0 -1
- package/dist/providers/azure.test.js +0 -330
- package/dist/providers/azure.test.js.map +0 -1
- package/dist/providers/config.d.ts +0 -87
- package/dist/providers/config.d.ts.map +0 -1
- package/dist/providers/config.js +0 -193
- package/dist/providers/config.js.map +0 -1
- package/dist/providers/config.test.d.ts +0 -7
- package/dist/providers/config.test.d.ts.map +0 -1
- package/dist/providers/config.test.js +0 -370
- package/dist/providers/config.test.js.map +0 -1
- package/dist/providers/index.d.ts +0 -18
- package/dist/providers/index.d.ts.map +0 -1
- package/dist/providers/index.js +0 -14
- package/dist/providers/index.js.map +0 -1
- package/dist/providers/interface.d.ts +0 -191
- package/dist/providers/interface.d.ts.map +0 -1
- package/dist/providers/interface.js +0 -94
- package/dist/providers/interface.js.map +0 -1
- package/dist/providers/retry.d.ts +0 -128
- package/dist/providers/retry.d.ts.map +0 -1
- package/dist/providers/retry.js +0 -205
- package/dist/providers/retry.js.map +0 -1
- package/dist/providers/retry.test.d.ts +0 -7
- package/dist/providers/retry.test.d.ts.map +0 -1
- package/dist/providers/retry.test.js +0 -439
- package/dist/providers/retry.test.js.map +0 -1
- package/dist/providers/streaming.d.ts +0 -157
- package/dist/providers/streaming.d.ts.map +0 -1
- package/dist/providers/streaming.js +0 -233
- package/dist/providers/streaming.js.map +0 -1
- package/dist/providers/streaming.test.d.ts +0 -7
- package/dist/providers/streaming.test.d.ts.map +0 -1
- package/dist/providers/streaming.test.js +0 -372
- package/dist/providers/streaming.test.js.map +0 -1
- package/dist/providers/types.d.ts +0 -209
- package/dist/providers/types.d.ts.map +0 -1
- package/dist/providers/types.js +0 -53
- package/dist/providers/types.js.map +0 -1
- package/dist/providers/types.test.d.ts +0 -7
- package/dist/providers/types.test.d.ts.map +0 -1
- package/dist/providers/types.test.js +0 -141
- package/dist/providers/types.test.js.map +0 -1
- package/dist/tools/cli/beads.d.ts +0 -27
- package/dist/tools/cli/beads.d.ts.map +0 -1
- package/dist/tools/cli/beads.js +0 -172
- package/dist/tools/cli/beads.js.map +0 -1
- package/dist/tools/cli/beads.test.d.ts +0 -8
- package/dist/tools/cli/beads.test.d.ts.map +0 -1
- package/dist/tools/cli/beads.test.js +0 -264
- package/dist/tools/cli/beads.test.js.map +0 -1
- package/dist/tools/cli/editFile.d.ts +0 -17
- package/dist/tools/cli/editFile.d.ts.map +0 -1
- package/dist/tools/cli/editFile.js +0 -125
- package/dist/tools/cli/editFile.js.map +0 -1
- package/dist/tools/cli/editFile.test.d.ts +0 -8
- package/dist/tools/cli/editFile.test.d.ts.map +0 -1
- package/dist/tools/cli/editFile.test.js +0 -177
- package/dist/tools/cli/editFile.test.js.map +0 -1
- package/dist/tools/cli/readFile.d.ts +0 -25
- package/dist/tools/cli/readFile.d.ts.map +0 -1
- package/dist/tools/cli/readFile.js +0 -118
- package/dist/tools/cli/readFile.js.map +0 -1
- package/dist/tools/cli/readFile.test.d.ts +0 -8
- package/dist/tools/cli/readFile.test.d.ts.map +0 -1
- package/dist/tools/cli/readFile.test.js +0 -194
- package/dist/tools/cli/readFile.test.js.map +0 -1
- package/dist/tools/cli/search.d.ts +0 -16
- package/dist/tools/cli/search.d.ts.map +0 -1
- package/dist/tools/cli/search.js +0 -261
- package/dist/tools/cli/search.js.map +0 -1
- package/dist/tools/cli/search.test.d.ts +0 -8
- package/dist/tools/cli/search.test.d.ts.map +0 -1
- package/dist/tools/cli/search.test.js +0 -172
- package/dist/tools/cli/search.test.js.map +0 -1
- package/dist/tools/cli/subagent.d.ts +0 -43
- package/dist/tools/cli/subagent.d.ts.map +0 -1
- package/dist/tools/cli/subagent.js +0 -99
- package/dist/tools/cli/subagent.js.map +0 -1
- package/dist/tools/cli/subagent.test.d.ts +0 -8
- package/dist/tools/cli/subagent.test.d.ts.map +0 -1
- package/dist/tools/cli/subagent.test.js +0 -190
- package/dist/tools/cli/subagent.test.js.map +0 -1
- package/dist/tools/cli/terminal.d.ts +0 -19
- package/dist/tools/cli/terminal.d.ts.map +0 -1
- package/dist/tools/cli/terminal.js +0 -164
- package/dist/tools/cli/terminal.js.map +0 -1
- package/dist/tools/cli/terminal.test.d.ts +0 -8
- package/dist/tools/cli/terminal.test.d.ts.map +0 -1
- package/dist/tools/cli/terminal.test.js +0 -161
- package/dist/tools/cli/terminal.test.js.map +0 -1
- package/dist/tools/index.d.ts +0 -25
- package/dist/tools/index.d.ts.map +0 -1
- package/dist/tools/index.js +0 -41
- package/dist/tools/index.js.map +0 -1
- package/dist/tools/interface.d.ts +0 -64
- package/dist/tools/interface.d.ts.map +0 -1
- package/dist/tools/interface.js +0 -37
- package/dist/tools/interface.js.map +0 -1
- package/dist/tools/interface.test.d.ts +0 -7
- package/dist/tools/interface.test.d.ts.map +0 -1
- package/dist/tools/interface.test.js +0 -179
- package/dist/tools/interface.test.js.map +0 -1
- package/dist/tools/mcp/bridge.d.ts +0 -48
- package/dist/tools/mcp/bridge.d.ts.map +0 -1
- package/dist/tools/mcp/bridge.js +0 -128
- package/dist/tools/mcp/bridge.js.map +0 -1
- package/dist/tools/mcp/bridge.test.d.ts +0 -8
- package/dist/tools/mcp/bridge.test.d.ts.map +0 -1
- package/dist/tools/mcp/bridge.test.js +0 -300
- package/dist/tools/mcp/bridge.test.js.map +0 -1
- package/dist/tools/mcp/client.d.ts +0 -135
- package/dist/tools/mcp/client.d.ts.map +0 -1
- package/dist/tools/mcp/client.js +0 -263
- package/dist/tools/mcp/client.js.map +0 -1
- package/dist/tools/mcp/client.test.d.ts +0 -8
- package/dist/tools/mcp/client.test.d.ts.map +0 -1
- package/dist/tools/mcp/client.test.js +0 -390
- package/dist/tools/mcp/client.test.js.map +0 -1
- package/dist/tools/registry.d.ts +0 -82
- package/dist/tools/registry.d.ts.map +0 -1
- package/dist/tools/registry.js +0 -99
- package/dist/tools/registry.js.map +0 -1
- package/dist/tools/registry.test.d.ts +0 -7
- package/dist/tools/registry.test.d.ts.map +0 -1
- package/dist/tools/registry.test.js +0 -199
- package/dist/tools/registry.test.js.map +0 -1
- package/dist/tools/suite.test.d.ts +0 -11
- package/dist/tools/suite.test.d.ts.map +0 -1
- package/dist/tools/suite.test.js +0 -119
- package/dist/tools/suite.test.js.map +0 -1
- package/dist/tools/types.d.ts +0 -75
- package/dist/tools/types.d.ts.map +0 -1
- package/dist/tools/types.js +0 -30
- package/dist/tools/types.js.map +0 -1
- package/dist/tools/types.test.d.ts +0 -7
- package/dist/tools/types.test.d.ts.map +0 -1
- package/dist/tools/types.test.js +0 -178
- package/dist/tools/types.test.js.map +0 -1
- package/templates/.vscode/mcp.json +0 -20
- package/templates/CLAUDE.md +0 -129
|
@@ -1,225 +1,217 @@
|
|
|
1
|
-
# Beth - AI Agent System
|
|
2
|
-
|
|
3
|
-
A ruthless, hyper-competent AI orchestrator for GitHub Copilot multi-agent workflows.
|
|
4
|
-
|
|
5
|
-
## Architecture Overview
|
|
6
|
-
|
|
7
|
-
```
|
|
8
|
-
.github/
|
|
9
|
-
├── agents/ # Agent definitions (*.agent.md frontmatter + instructions)
|
|
10
|
-
├── skills/ # Domain knowledge for specific capabilities (SKILL.md files)
|
|
11
|
-
└── appmod/ # App modernization configurations
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
**Key insight**: Agents are role-based specialists (PM, Developer, Designer, etc.) while skills are domain-specific knowledge modules that agents load on-demand.
|
|
15
|
-
|
|
16
|
-
## Agent System
|
|
17
|
-
|
|
18
|
-
### Agent Definition Format
|
|
19
|
-
Agents use `.agent.md` files with YAML frontmatter defining:
|
|
20
|
-
- `name`, `description`, `model` - Identity
|
|
21
|
-
- `tools` - Available capabilities (codebase, readFile, editFiles, runSubagent, etc.)
|
|
22
|
-
- `handoffs` - Other agents this agent can transfer control to
|
|
23
|
-
- `infer: true` - Enables the agent to be invoked as a subagent
|
|
24
|
-
|
|
25
|
-
### The Seven Agents
|
|
26
|
-
| Agent | Purpose | Primary Tools |
|
|
27
|
-
|-------|---------|---------------|
|
|
28
|
-
| `Beth` | Orchestrator - Routes work, spawns subagents | `runSubagent`, search tools |
|
|
29
|
-
| `product-manager` | WHAT to build: PRDs, user stories, priorities, success metrics | PRD skill |
|
|
30
|
-
| `researcher` | User/market research, competitive analysis | Research synthesis |
|
|
31
|
-
| `ux-designer` | HOW it works: component specs, design tokens, accessibility | Framer skill |
|
|
32
|
-
| `developer` | React/TypeScript/Next.js - UI and full-stack | shadcn-ui skill, shadcn MCP, all editing tools |
|
|
33
|
-
| `security-reviewer` | Security audits, threat modeling, compliance | security-analysis skill |
|
|
34
|
-
| `tester` | QA, accessibility, performance testing | Testing tools |
|
|
35
|
-
|
|
36
|
-
### Product Manager vs UX Designer
|
|
37
|
-
|
|
38
|
-
These agents serve distinct purposes in the IDEO workflow:
|
|
39
|
-
|
|
40
|
-
| | Product Manager | UX Designer |
|
|
41
|
-
|---|---|---|
|
|
42
|
-
| **Focus** | WHAT to build, WHY, WHEN | HOW it looks, feels, behaves |
|
|
43
|
-
| **Outputs** | PRDs, user stories, RICE scores, roadmaps | Component specs, wireframes, design tokens, accessibility requirements |
|
|
44
|
-
| **Key Question** | "Is this worth building?" | "How should this work?" |
|
|
45
|
-
| **Example** | "Users need date filtering" (acceptance criteria) | "The date picker has these variants, states, and ARIA attributes" (spec) |
|
|
46
|
-
|
|
47
|
-
**Use Product Manager** when defining requirements, prioritizing features, or making build/no-build decisions.
|
|
48
|
-
**Use UX Designer** when specifying component behavior, design systems, or accessibility compliance.
|
|
49
|
-
|
|
50
|
-
### Subagent vs Handoff Pattern
|
|
51
|
-
- **Handoffs**: User clicks button → context transferred → user reviews
|
|
52
|
-
- **Subagents**: Autonomous execution → results returned → continue workflow
|
|
53
|
-
|
|
54
|
-
```typescript
|
|
55
|
-
// Subagent invocation pattern
|
|
56
|
-
runSubagent({
|
|
57
|
-
agentName: "researcher",
|
|
58
|
-
prompt: "Detailed task with expected output format...",
|
|
59
|
-
description: "3-5 word description"
|
|
60
|
-
})
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
## Skills System
|
|
64
|
-
|
|
65
|
-
Skills are domain-knowledge modules in `.github/skills/<name>/SKILL.md`. Agents load skills when triggered by specific phrases.
|
|
66
|
-
|
|
67
|
-
| Skill | Location | Triggers |
|
|
68
|
-
|-------|----------|----------|
|
|
69
|
-
| PRD Generation | `skills/prd/` | "create a prd", "product requirements" |
|
|
70
|
-
| Framer Components | `skills/framer-components/` | "framer component", "property controls" |
|
|
71
|
-
| Vercel React Best Practices | `skills/vercel-react-best-practices/` | React/Next.js performance work |
|
|
72
|
-
| Web Design Guidelines | `skills/web-design-guidelines/` | "review my UI", "check accessibility" |
|
|
73
|
-
| shadcn/ui Components | `skills/shadcn-ui/` | "shadcn", "ui component", component installation |
|
|
74
|
-
| Security Analysis | `skills/security-analysis/` | "security review", "OWASP", "threat model", "compliance" |
|
|
75
|
-
|
|
76
|
-
## Development Conventions
|
|
77
|
-
|
|
78
|
-
### Tech Stack
|
|
79
|
-
- **React 19** with Server Components, Server Actions, `use`, `useOptimistic`
|
|
80
|
-
- **Next.js App Router** with streaming, Suspense, parallel routes
|
|
81
|
-
- **TypeScript** in strict mode, Zod for runtime validation
|
|
82
|
-
- **Styling**: Tailwind CSS with `class-variance-authority` (cva)
|
|
83
|
-
|
|
84
|
-
### Code Patterns
|
|
85
|
-
|
|
86
|
-
**Server Components as default** - Only add `'use client'` when needed for interactivity:
|
|
87
|
-
```typescript
|
|
88
|
-
// Server Component (default)
|
|
89
|
-
export default async function Page() {
|
|
90
|
-
const data = await fetchData();
|
|
91
|
-
return <Display data={data} />;
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
// Client Component (when needed)
|
|
95
|
-
'use client';
|
|
96
|
-
export function InteractiveWidget() { ... }
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
**Server Actions for mutations**:
|
|
100
|
-
```typescript
|
|
101
|
-
'use server';
|
|
102
|
-
export async function updateItem(formData: FormData) {
|
|
103
|
-
const parsed = Schema.safeParse(Object.fromEntries(formData));
|
|
104
|
-
if (!parsed.success) return { error: 'Invalid input' };
|
|
105
|
-
// mutation logic
|
|
106
|
-
revalidatePath('/path');
|
|
107
|
-
}
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
### Quality Standards
|
|
111
|
-
- WCAG 2.1 AA accessibility compliance
|
|
112
|
-
- Core Web Vitals in green (LCP < 2.5s, FID < 100ms, CLS < 0.1)
|
|
113
|
-
- Full TypeScript coverage, no `any`
|
|
114
|
-
- Unit tests for utilities, integration tests for features
|
|
115
|
-
|
|
116
|
-
## IDEO Design Thinking Integration
|
|
117
|
-
|
|
118
|
-
Apply human-centered design methodology across agent workflows:
|
|
119
|
-
|
|
120
|
-
| Phase | Agent | Activities |
|
|
121
|
-
|-------|-------|------------|
|
|
122
|
-
| **Empathize** | `@researcher` | User interviews, observation, pain point discovery |
|
|
123
|
-
| **Define** | `@product-manager` | Problem framing, requirements, success criteria |
|
|
124
|
-
| **Ideate** | `@ux-designer` | Solution exploration, design patterns, prototypes |
|
|
125
|
-
| **Prototype** | `@developer` | Build to learn, rapid iteration, feature spikes |
|
|
126
|
-
| **Test** | `@tester` | Validate assumptions, accessibility audits, performance |
|
|
127
|
-
|
|
128
|
-
Balance the three lenses: **Desirability** (user wants), **Feasibility** (technically possible), **Viability** (sustainable for business).
|
|
129
|
-
|
|
130
|
-
## React/Next.js Performance Patterns
|
|
131
|
-
|
|
132
|
-
Critical optimizations from [.github/skills/vercel-react-best-practices/AGENTS.md](.github/skills/vercel-react-best-practices/AGENTS.md):
|
|
133
|
-
|
|
134
|
-
### Eliminate Waterfalls (CRITICAL)
|
|
135
|
-
```typescript
|
|
136
|
-
// ❌ Sequential: 3 round trips
|
|
137
|
-
const user = await fetchUser();
|
|
138
|
-
const posts = await fetchPosts();
|
|
139
|
-
const comments = await fetchComments();
|
|
140
|
-
|
|
141
|
-
// ✅ Parallel: 1 round trip
|
|
142
|
-
const [user, posts, comments] = await Promise.all([
|
|
143
|
-
fetchUser(), fetchPosts(), fetchComments()
|
|
144
|
-
]);
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
### Strategic Suspense Boundaries
|
|
148
|
-
```tsx
|
|
149
|
-
// Wrapper renders immediately, data streams in
|
|
150
|
-
function Page() {
|
|
151
|
-
return (
|
|
152
|
-
<div>
|
|
153
|
-
<Header />
|
|
154
|
-
<Suspense fallback={<Skeleton />}>
|
|
155
|
-
<DataDisplay /> {/* Only this awaits data */}
|
|
156
|
-
</Suspense>
|
|
157
|
-
<Footer />
|
|
158
|
-
</div>
|
|
159
|
-
);
|
|
160
|
-
}
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
### Bundle Size Optimization
|
|
164
|
-
- **Avoid barrel imports**: `import { Check } from 'lucide-react'` → `import Check from 'lucide-react/dist/esm/icons/check'`
|
|
165
|
-
- **Dynamic imports**: Use `next/dynamic` for heavy components (Monaco, charts)
|
|
166
|
-
- **Defer non-critical**: Load analytics/tracking after hydration with `ssr: false`
|
|
167
|
-
|
|
168
|
-
### Server Action Security
|
|
169
|
-
Always authenticate inside Server Actions—they're public endpoints:
|
|
170
|
-
```typescript
|
|
171
|
-
'use server';
|
|
172
|
-
export async function deleteUser(userId: string) {
|
|
173
|
-
const session = await verifySession();
|
|
174
|
-
if (!session || session.user.id !== userId) throw unauthorized();
|
|
175
|
-
// proceed with mutation
|
|
176
|
-
}
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
## Workflow Patterns
|
|
180
|
-
|
|
181
|
-
### New Feature Flow
|
|
182
|
-
1. `@Beth` → analyzes request, proposes workflow
|
|
183
|
-
2. `@product-manager` → defines requirements (uses PRD skill)
|
|
184
|
-
3. `@researcher` → validates user needs (optional)
|
|
185
|
-
4. `@ux-designer` → designs interface
|
|
186
|
-
5. `@developer` → implements in React/TypeScript
|
|
187
|
-
6. `@security-reviewer` → audits for vulnerabilities
|
|
188
|
-
7. `@tester` → verifies quality
|
|
189
|
-
|
|
190
|
-
### Quick Commands
|
|
191
|
-
```
|
|
192
|
-
@Beth Plan a feature for [description]
|
|
193
|
-
@product-manager Create a PRD for [feature]
|
|
194
|
-
@developer Implement [component/feature]
|
|
195
|
-
@tester Write tests for [component]
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
##
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
## File Naming Conventions
|
|
220
|
-
|
|
221
|
-
- Agents: `.github/agents/<name>.agent.md`
|
|
222
|
-
- Skills: `.github/skills/<skill-name>/SKILL.md`
|
|
223
|
-
- Components: `components/<Name>/<Name>.tsx` with `index.tsx` barrel
|
|
224
|
-
- Server Actions: `lib/actions/<domain>.ts`
|
|
225
|
-
- Data fetching: `lib/data/<domain>.ts`
|
|
1
|
+
# Beth - AI Agent System
|
|
2
|
+
|
|
3
|
+
A ruthless, hyper-competent AI orchestrator for GitHub Copilot multi-agent workflows.
|
|
4
|
+
|
|
5
|
+
## Architecture Overview
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
.github/
|
|
9
|
+
├── agents/ # Agent definitions (*.agent.md frontmatter + instructions)
|
|
10
|
+
├── skills/ # Domain knowledge for specific capabilities (SKILL.md files)
|
|
11
|
+
└── appmod/ # App modernization configurations
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
**Key insight**: Agents are role-based specialists (PM, Developer, Designer, etc.) while skills are domain-specific knowledge modules that agents load on-demand.
|
|
15
|
+
|
|
16
|
+
## Agent System
|
|
17
|
+
|
|
18
|
+
### Agent Definition Format
|
|
19
|
+
Agents use `.agent.md` files with YAML frontmatter defining:
|
|
20
|
+
- `name`, `description`, `model` - Identity
|
|
21
|
+
- `tools` - Available capabilities (codebase, readFile, editFiles, runSubagent, etc.)
|
|
22
|
+
- `handoffs` - Other agents this agent can transfer control to
|
|
23
|
+
- `infer: true` - Enables the agent to be invoked as a subagent
|
|
24
|
+
|
|
25
|
+
### The Seven Agents
|
|
26
|
+
| Agent | Purpose | Primary Tools |
|
|
27
|
+
|-------|---------|---------------|
|
|
28
|
+
| `Beth` | Orchestrator - Routes work, spawns subagents | `runSubagent`, search tools |
|
|
29
|
+
| `product-manager` | WHAT to build: PRDs, user stories, priorities, success metrics | PRD skill |
|
|
30
|
+
| `researcher` | User/market research, competitive analysis | Research synthesis |
|
|
31
|
+
| `ux-designer` | HOW it works: component specs, design tokens, accessibility | Framer skill |
|
|
32
|
+
| `developer` | React/TypeScript/Next.js - UI and full-stack | shadcn-ui skill, shadcn MCP, all editing tools |
|
|
33
|
+
| `security-reviewer` | Security audits, threat modeling, compliance | security-analysis skill |
|
|
34
|
+
| `tester` | QA, accessibility, performance testing | Testing tools |
|
|
35
|
+
|
|
36
|
+
### Product Manager vs UX Designer
|
|
37
|
+
|
|
38
|
+
These agents serve distinct purposes in the IDEO workflow:
|
|
39
|
+
|
|
40
|
+
| | Product Manager | UX Designer |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| **Focus** | WHAT to build, WHY, WHEN | HOW it looks, feels, behaves |
|
|
43
|
+
| **Outputs** | PRDs, user stories, RICE scores, roadmaps | Component specs, wireframes, design tokens, accessibility requirements |
|
|
44
|
+
| **Key Question** | "Is this worth building?" | "How should this work?" |
|
|
45
|
+
| **Example** | "Users need date filtering" (acceptance criteria) | "The date picker has these variants, states, and ARIA attributes" (spec) |
|
|
46
|
+
|
|
47
|
+
**Use Product Manager** when defining requirements, prioritizing features, or making build/no-build decisions.
|
|
48
|
+
**Use UX Designer** when specifying component behavior, design systems, or accessibility compliance.
|
|
49
|
+
|
|
50
|
+
### Subagent vs Handoff Pattern
|
|
51
|
+
- **Handoffs**: User clicks button → context transferred → user reviews
|
|
52
|
+
- **Subagents**: Autonomous execution → results returned → continue workflow
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
// Subagent invocation pattern
|
|
56
|
+
runSubagent({
|
|
57
|
+
agentName: "researcher",
|
|
58
|
+
prompt: "Detailed task with expected output format...",
|
|
59
|
+
description: "3-5 word description"
|
|
60
|
+
})
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Skills System
|
|
64
|
+
|
|
65
|
+
Skills are domain-knowledge modules in `.github/skills/<name>/SKILL.md`. Agents load skills when triggered by specific phrases.
|
|
66
|
+
|
|
67
|
+
| Skill | Location | Triggers |
|
|
68
|
+
|-------|----------|----------|
|
|
69
|
+
| PRD Generation | `skills/prd/` | "create a prd", "product requirements" |
|
|
70
|
+
| Framer Components | `skills/framer-components/` | "framer component", "property controls" |
|
|
71
|
+
| Vercel React Best Practices | `skills/vercel-react-best-practices/` | React/Next.js performance work |
|
|
72
|
+
| Web Design Guidelines | `skills/web-design-guidelines/` | "review my UI", "check accessibility" |
|
|
73
|
+
| shadcn/ui Components | `skills/shadcn-ui/` | "shadcn", "ui component", component installation |
|
|
74
|
+
| Security Analysis | `skills/security-analysis/` | "security review", "OWASP", "threat model", "compliance" |
|
|
75
|
+
|
|
76
|
+
## Development Conventions
|
|
77
|
+
|
|
78
|
+
### Tech Stack
|
|
79
|
+
- **React 19** with Server Components, Server Actions, `use`, `useOptimistic`
|
|
80
|
+
- **Next.js App Router** with streaming, Suspense, parallel routes
|
|
81
|
+
- **TypeScript** in strict mode, Zod for runtime validation
|
|
82
|
+
- **Styling**: Tailwind CSS with `class-variance-authority` (cva)
|
|
83
|
+
|
|
84
|
+
### Code Patterns
|
|
85
|
+
|
|
86
|
+
**Server Components as default** - Only add `'use client'` when needed for interactivity:
|
|
87
|
+
```typescript
|
|
88
|
+
// Server Component (default)
|
|
89
|
+
export default async function Page() {
|
|
90
|
+
const data = await fetchData();
|
|
91
|
+
return <Display data={data} />;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
// Client Component (when needed)
|
|
95
|
+
'use client';
|
|
96
|
+
export function InteractiveWidget() { ... }
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Server Actions for mutations**:
|
|
100
|
+
```typescript
|
|
101
|
+
'use server';
|
|
102
|
+
export async function updateItem(formData: FormData) {
|
|
103
|
+
const parsed = Schema.safeParse(Object.fromEntries(formData));
|
|
104
|
+
if (!parsed.success) return { error: 'Invalid input' };
|
|
105
|
+
// mutation logic
|
|
106
|
+
revalidatePath('/path');
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Quality Standards
|
|
111
|
+
- WCAG 2.1 AA accessibility compliance
|
|
112
|
+
- Core Web Vitals in green (LCP < 2.5s, FID < 100ms, CLS < 0.1)
|
|
113
|
+
- Full TypeScript coverage, no `any`
|
|
114
|
+
- Unit tests for utilities, integration tests for features
|
|
115
|
+
|
|
116
|
+
## IDEO Design Thinking Integration
|
|
117
|
+
|
|
118
|
+
Apply human-centered design methodology across agent workflows:
|
|
119
|
+
|
|
120
|
+
| Phase | Agent | Activities |
|
|
121
|
+
|-------|-------|------------|
|
|
122
|
+
| **Empathize** | `@researcher` | User interviews, observation, pain point discovery |
|
|
123
|
+
| **Define** | `@product-manager` | Problem framing, requirements, success criteria |
|
|
124
|
+
| **Ideate** | `@ux-designer` | Solution exploration, design patterns, prototypes |
|
|
125
|
+
| **Prototype** | `@developer` | Build to learn, rapid iteration, feature spikes |
|
|
126
|
+
| **Test** | `@tester` | Validate assumptions, accessibility audits, performance |
|
|
127
|
+
|
|
128
|
+
Balance the three lenses: **Desirability** (user wants), **Feasibility** (technically possible), **Viability** (sustainable for business).
|
|
129
|
+
|
|
130
|
+
## React/Next.js Performance Patterns
|
|
131
|
+
|
|
132
|
+
Critical optimizations from [.github/skills/vercel-react-best-practices/AGENTS.md](.github/skills/vercel-react-best-practices/AGENTS.md):
|
|
133
|
+
|
|
134
|
+
### Eliminate Waterfalls (CRITICAL)
|
|
135
|
+
```typescript
|
|
136
|
+
// ❌ Sequential: 3 round trips
|
|
137
|
+
const user = await fetchUser();
|
|
138
|
+
const posts = await fetchPosts();
|
|
139
|
+
const comments = await fetchComments();
|
|
140
|
+
|
|
141
|
+
// ✅ Parallel: 1 round trip
|
|
142
|
+
const [user, posts, comments] = await Promise.all([
|
|
143
|
+
fetchUser(), fetchPosts(), fetchComments()
|
|
144
|
+
]);
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Strategic Suspense Boundaries
|
|
148
|
+
```tsx
|
|
149
|
+
// Wrapper renders immediately, data streams in
|
|
150
|
+
function Page() {
|
|
151
|
+
return (
|
|
152
|
+
<div>
|
|
153
|
+
<Header />
|
|
154
|
+
<Suspense fallback={<Skeleton />}>
|
|
155
|
+
<DataDisplay /> {/* Only this awaits data */}
|
|
156
|
+
</Suspense>
|
|
157
|
+
<Footer />
|
|
158
|
+
</div>
|
|
159
|
+
);
|
|
160
|
+
}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### Bundle Size Optimization
|
|
164
|
+
- **Avoid barrel imports**: `import { Check } from 'lucide-react'` → `import Check from 'lucide-react/dist/esm/icons/check'`
|
|
165
|
+
- **Dynamic imports**: Use `next/dynamic` for heavy components (Monaco, charts)
|
|
166
|
+
- **Defer non-critical**: Load analytics/tracking after hydration with `ssr: false`
|
|
167
|
+
|
|
168
|
+
### Server Action Security
|
|
169
|
+
Always authenticate inside Server Actions—they're public endpoints:
|
|
170
|
+
```typescript
|
|
171
|
+
'use server';
|
|
172
|
+
export async function deleteUser(userId: string) {
|
|
173
|
+
const session = await verifySession();
|
|
174
|
+
if (!session || session.user.id !== userId) throw unauthorized();
|
|
175
|
+
// proceed with mutation
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Workflow Patterns
|
|
180
|
+
|
|
181
|
+
### New Feature Flow
|
|
182
|
+
1. `@Beth` → analyzes request, proposes workflow
|
|
183
|
+
2. `@product-manager` → defines requirements (uses PRD skill)
|
|
184
|
+
3. `@researcher` → validates user needs (optional)
|
|
185
|
+
4. `@ux-designer` → designs interface
|
|
186
|
+
5. `@developer` → implements in React/TypeScript
|
|
187
|
+
6. `@security-reviewer` → audits for vulnerabilities
|
|
188
|
+
7. `@tester` → verifies quality
|
|
189
|
+
|
|
190
|
+
### Quick Commands
|
|
191
|
+
```
|
|
192
|
+
@Beth Plan a feature for [description]
|
|
193
|
+
@product-manager Create a PRD for [feature]
|
|
194
|
+
@developer Implement [component/feature]
|
|
195
|
+
@tester Write tests for [component]
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Branch Discipline
|
|
199
|
+
|
|
200
|
+
All non-trivial work happens on **epic branches** (`epic/<epic-id>`). See `AGENTS.md` for the full Branch Discipline rules.
|
|
201
|
+
|
|
202
|
+
Key points:
|
|
203
|
+
- **Every new chat session creates a fresh epic branch from `main`** — Beth does this automatically before any work begins
|
|
204
|
+
- Beth correlates every request to an epic and ensures the correct branch is checked out before work begins
|
|
205
|
+
- Epic branches are named `epic/<epic-id>` (e.g., `epic/beth-abc123`)
|
|
206
|
+
- All commits use the prefix `<epic-id>: description`
|
|
207
|
+
- Subagents inherit the epic branch and must verify before making changes
|
|
208
|
+
- Multiple Beth instances work on different epic branches to avoid conflicts
|
|
209
|
+
- **When landing the plane, Beth pushes the branch and creates a PR to `main`** via GitHub MCP
|
|
210
|
+
|
|
211
|
+
## File Naming Conventions
|
|
212
|
+
|
|
213
|
+
- Agents: `.github/agents/<name>.agent.md`
|
|
214
|
+
- Skills: `.github/skills/<skill-name>/SKILL.md`
|
|
215
|
+
- Components: `components/<Name>/<Name>.tsx` with `index.tsx` barrel
|
|
216
|
+
- Server Actions: `lib/actions/<domain>.ts`
|
|
217
|
+
- Data fetching: `lib/data/<domain>.ts`
|
package/templates/AGENTS.md
CHANGED
|
@@ -44,52 +44,140 @@ bd ready
|
|
|
44
44
|
# View dependencies
|
|
45
45
|
bd dep tree <id>
|
|
46
46
|
|
|
47
|
-
# Close an issue
|
|
48
|
-
|
|
47
|
+
# Close an issue (enforced — checks for open children)
|
|
48
|
+
npx beth-copilot close <id>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
+
## Session Startup (MANDATORY)
|
|
52
|
+
|
|
53
|
+
**Every new session starts by verifying ground truth.** Trackers lie. Code doesn't.
|
|
54
|
+
|
|
55
|
+
Before picking up new work — even continuing previous work — complete these checks:
|
|
56
|
+
|
|
57
|
+
### 1. Check for uncommitted changes (formatter reverts)
|
|
58
|
+
```bash
|
|
59
|
+
git status
|
|
60
|
+
git diff --stat
|
|
61
|
+
```
|
|
62
|
+
Formatters, editors, and VS Code extensions can silently revert agent changes between sessions. If you see unexpected diffs, investigate before proceeding.
|
|
63
|
+
|
|
64
|
+
### 2. Check for unpushed commits
|
|
65
|
+
```bash
|
|
66
|
+
git log --oneline origin/$(git branch --show-current)..HEAD
|
|
67
|
+
```
|
|
68
|
+
If there are unpushed commits from a previous session, push them or understand why they weren't pushed.
|
|
69
|
+
|
|
70
|
+
### 3. Spot-check closed work is intact
|
|
71
|
+
Pick 1-2 issues closed in the last session and verify the changes are actually in the code:
|
|
72
|
+
```bash
|
|
73
|
+
# Example: verify an import was actually added
|
|
74
|
+
grep -r "import.*ComponentName" src/
|
|
75
|
+
```
|
|
76
|
+
If beads says "done" but the code disagrees, reopen the issue and re-apply the fix.
|
|
77
|
+
|
|
78
|
+
### 4. Sync beads state
|
|
79
|
+
```bash
|
|
80
|
+
bd list
|
|
81
|
+
bd ready
|
|
82
|
+
```
|
|
83
|
+
Verify beads reflects reality before creating new work.
|
|
84
|
+
|
|
85
|
+
### The principle: Trust the code, not the tracker
|
|
86
|
+
|
|
87
|
+
> **War story (March 7, 2026):** A formatter reverted a critical routing file back to importing an old component. The tracking issue said "routing wired up" but the code was back to the previous state. It was caught and fixed — but only because we checked.
|
|
88
|
+
|
|
89
|
+
This can happen to ANY file touched by agents. The most vulnerable are files touched by formatters on save (page.tsx, component files with import changes). When in doubt, check the code.
|
|
90
|
+
|
|
91
|
+
### Beads known issues
|
|
92
|
+
|
|
93
|
+
> **War story (March 9, 2026): Test pollution.** E2E tests for `bd` commands create real issues in the Dolt database. If `afterAll` cleanup doesn't run (crash, timeout, process kill), orphan "E2E test:" issues pollute `bd list` and `bd ready`, hiding real work behind 30+ garbage entries. **Fix:** `beads.e2e.test.ts` now runs a `beforeAll` safety net that searches for stale "E2E test:" issues and batch-deletes them before creating new ones. Cleanup also uses `bd delete --from-file` for speed instead of per-issue `execSync` loops.
|
|
94
|
+
|
|
95
|
+
> **War story (March 9, 2026): Tracking drift.** An epic (beth-gau) was planned in Backlog.md with 7 detailed subtasks but never created in beads. A new session saw the Backlog.md entry, tried `bd show beth-gau`, got "not found" (intermittent ID resolution), and created a duplicate epic. The duplicate was a phantom (Dolt transaction didn't persist). **Fix:** When checking for existing work, always use `bd list --json` as the source of truth — not `bd show`, which has intermittent resolution failures. And ALWAYS create beads issues before (or simultaneously with) Backlog.md entries.
|
|
96
|
+
|
|
97
|
+
> **Rule: beads and Backlog.md must be created together.** If it's in Backlog.md, it must be in beads. If it's in beads, the summary must be in Backlog.md. One system without the other is a lie waiting to cause damage.
|
|
98
|
+
|
|
51
99
|
## Workflow
|
|
52
100
|
|
|
53
101
|
### Simple Tasks
|
|
54
102
|
1. `bd create "Task" -l in_progress`
|
|
55
103
|
2. Do the work
|
|
56
|
-
3. `
|
|
104
|
+
3. `npx beth-copilot close <id>`
|
|
57
105
|
4. Update Backlog.md if significant
|
|
58
106
|
5. Commit and push
|
|
59
107
|
|
|
60
108
|
### Complex Work (Multi-Agent)
|
|
61
109
|
1. `bd create "Feature" --type epic -p 1`
|
|
62
|
-
2.
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
110
|
+
2. **Create/checkout** the epic branch from main:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
git fetch origin main
|
|
114
|
+
git checkout -b epic/<epic-id> origin/main
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
3. Break into subtasks with `--parent` and `--deps`
|
|
118
|
+
4. **Create MANDATORY test subtasks** for every implementation task:
|
|
119
|
+
```bash
|
|
120
|
+
bd create "Unit tests for <feature>" --parent <epic-id> --deps "<impl-id>"
|
|
121
|
+
bd create "E2E tests for <feature>" --parent <epic-id> --deps "<impl-id>"
|
|
122
|
+
bd create "Security tests for <feature>" --parent <epic-id> --deps "<impl-id>"
|
|
123
|
+
```
|
|
124
|
+
5. `bd ready` to find unblocked work
|
|
125
|
+
6. Route to specialists with issue IDs **and branch name**
|
|
126
|
+
7. Close subtasks as they complete
|
|
127
|
+
8. `bd epic close-eligible` when all children done
|
|
128
|
+
9. Update Backlog.md with summary
|
|
129
|
+
10. Push the epic branch
|
|
130
|
+
11. **Create a PR to `main`** using GitHub MCP (`mcp_github2_create_pull_request`)
|
|
69
131
|
|
|
70
132
|
## Landing the Plane (Session Completion)
|
|
71
133
|
|
|
72
|
-
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
|
|
134
|
+
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds AND the PR is created.
|
|
73
135
|
|
|
74
136
|
**MANDATORY WORKFLOW:**
|
|
75
137
|
|
|
76
|
-
1. **Close beads issues** - `
|
|
138
|
+
1. **Close beads issues** - `npx beth-copilot close <id>` for completed work
|
|
77
139
|
2. **Create follow-up issues** - `bd create` for any remaining work
|
|
78
140
|
3. **Update Backlog.md** - Add summary to Completed section for significant work
|
|
79
|
-
4. **Run quality gates** (if code changed) -
|
|
80
|
-
|
|
141
|
+
4. **Run quality gates** (if code changed) - ALL tests must pass:
|
|
142
|
+
```bash
|
|
143
|
+
npm test # Unit + integration tests
|
|
144
|
+
# If failures: create follow-up issues, DO NOT close parent issue
|
|
145
|
+
```
|
|
146
|
+
5. **Generate test report** (if code changed):
|
|
147
|
+
```bash
|
|
148
|
+
npm run test:gate # Runs tests + generates docs/test-reports/ report
|
|
149
|
+
```
|
|
150
|
+
6. **PUSH TO EPIC BRANCH** - This is MANDATORY:
|
|
151
|
+
|
|
81
152
|
```bash
|
|
82
153
|
git add -A
|
|
83
|
-
git commit -m "description of work"
|
|
84
|
-
git pull --rebase
|
|
85
|
-
git push
|
|
154
|
+
git commit -m "<epic-id>: description of work"
|
|
155
|
+
git pull origin "epic/<epic-id>" --rebase
|
|
156
|
+
git push origin "epic/<epic-id>"
|
|
86
157
|
git status # MUST show "up to date with origin"
|
|
87
158
|
```
|
|
88
|
-
|
|
89
|
-
|
|
159
|
+
|
|
160
|
+
6. **CREATE A PR TO `main`** - Use GitHub MCP to create a pull request:
|
|
161
|
+
|
|
162
|
+
```text
|
|
163
|
+
mcp_github2_create_pull_request(
|
|
164
|
+
owner: <repo-owner>,
|
|
165
|
+
repo: <repo-name>,
|
|
166
|
+
title: "<epic-id>: <summary of work>",
|
|
167
|
+
head: "epic/<epic-id>",
|
|
168
|
+
base: "main",
|
|
169
|
+
body: "## Summary\n<what was done>\n\n## Epic\n<epic-id>\n\n## Changes\n<list of changes>",
|
|
170
|
+
draft: false
|
|
171
|
+
)
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
7. **Share the PR link** with the user
|
|
175
|
+
8. **Hand off** - Provide context for next session including the epic ID, branch, and PR URL
|
|
90
176
|
|
|
91
177
|
**CRITICAL RULES:**
|
|
92
|
-
|
|
178
|
+
|
|
179
|
+
- Work is NOT complete until `git push` succeeds AND the PR is created
|
|
93
180
|
- NEVER stop before pushing - that leaves work stranded locally
|
|
94
181
|
- NEVER say "ready to push when you are" - YOU must push
|
|
95
182
|
- If push fails, resolve and retry until it succeeds
|
|
183
|
+
- The PR is how humans review your work. No PR = no review = no trust.
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Client Configuration Persistence and Detection
|
|
3
|
-
*
|
|
4
|
-
* Persists the user's AI client selection (VS Code, Copilot CLI, Claude Code)
|
|
5
|
-
* to `.github/.beth-client.json` so other commands can detect which client
|
|
6
|
-
* was chosen during `init`.
|
|
7
|
-
*
|
|
8
|
-
* Falls back to marker file detection when no config file exists.
|
|
9
|
-
*/
|
|
10
|
-
export interface ClientSelection {
|
|
11
|
-
vscode: boolean;
|
|
12
|
-
copilotCli: boolean;
|
|
13
|
-
claudeCode: boolean;
|
|
14
|
-
}
|
|
15
|
-
export declare const CLIENT_CONFIG_FILE = ".beth-client.json";
|
|
16
|
-
export declare const CLIENT_CONFIG_DIR = ".github";
|
|
17
|
-
/**
|
|
18
|
-
* Persist the client selection to `.github/.beth-client.json`.
|
|
19
|
-
* Creates the `.github/` directory if it doesn't exist.
|
|
20
|
-
* Overwrites any existing config file.
|
|
21
|
-
*/
|
|
22
|
-
export declare function persistClientConfig(cwd: string, clients: ClientSelection): void;
|
|
23
|
-
/**
|
|
24
|
-
* Detect the client configuration.
|
|
25
|
-
*
|
|
26
|
-
* 1. Tries to read `.github/.beth-client.json`
|
|
27
|
-
* 2. Falls back to marker file detection if config is missing or invalid
|
|
28
|
-
* 3. Defaults to `{ vscode: true, copilotCli: false, claudeCode: false }` if nothing detected
|
|
29
|
-
*/
|
|
30
|
-
export declare function detectClientConfig(cwd: string): ClientSelection;
|
|
31
|
-
//# sourceMappingURL=client-config.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"client-config.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/client-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AACtD,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAO/E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAiB/D"}
|