Skip to content

Commit 464e40d

Browse files
tarrencevtarrencev
committed
chore: agentic standards
1 parent 24a2438 commit 464e40d

File tree

13 files changed

+867
-0
lines changed

13 files changed

+867
-0
lines changed

‎.agents/skills/create-a-plan/SKILL.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
name: create-a-plan
3+
description: Conduct a focused technical planning interview to produce an implementable, parallelizable plan or spec with clear dependencies, risks, and open questions.
4+
---
5+
6+
# Create a Plan Skill
7+
8+
This skill runs a structured technical interview to turn a rough idea or an existing spec into a detailed, implementable plan. The output is organized for parallel execution: foundations first, then independent workstreams, then merge and integration.
9+
10+
## Invocation
11+
12+
The user will provide one of:
13+
- A path to a spec or plan file (for example: `SPEC.md`, `PLAN.md`, `RFC.md`)
14+
- A rough description of what they want to build
15+
- A feature request or problem statement
16+
17+
Output is always written to `PLAN.md` in the repo root.
18+
19+
## Process
20+
21+
### Phase 0: Preflight
22+
23+
1. If a file path is provided, read it first and note goals, non-goals, constraints, and gaps.
24+
2. Confirm you will produce `PLAN.md` as the output in the repo root. If `PLAN.md` already exists, update it rather than creating a new file.
25+
26+
### Phase 1: Discovery
27+
28+
Summarize what is known, then identify missing details. Focus on:
29+
- Goals and non-goals
30+
- Constraints (time, budget, platform, dependencies)
31+
- Success metrics and acceptance criteria
32+
33+
### Phase 2: Deep Interview
34+
35+
Use the `AskUserQuestion` (Claude) and/or `request_user_input` (Codex) tools in rounds. Ask 1-3 questions per round. Each round should go deeper and avoid repeating what is already known.
36+
37+
CRITICAL RULES:
38+
1. Never ask obvious questions. If the codebase or spec already answers it, do not ask it again.
39+
2. Ask about edge cases and failure modes.
40+
3. Probe for hidden complexity (state transitions, migrations, concurrency).
41+
4. Challenge assumptions when they create risk or ambiguity.
42+
5. Identify parallelization boundaries and serial dependencies.
43+
6. If the user is unsure, propose a default and ask for confirmation.
44+
45+
Question categories to cover as relevant:
46+
- Technical architecture and data flow
47+
- Data model and state management
48+
- API contracts and versioning
49+
- Caching and invalidation
50+
- Background jobs, retries, and idempotency
51+
- Error handling and recovery
52+
- Observability and debugging
53+
- Performance, scale, and SLAs
54+
- Security, privacy, and compliance
55+
- Integrations and external dependencies
56+
- UX flows, accessibility, and responsiveness
57+
- Rollout, migration, and rollback
58+
- Testing strategy and validation
59+
60+
### Phase 3: Dependency Analysis
61+
62+
Identify:
63+
1. Serial dependencies that must complete first
64+
2. Parallel workstreams that can run independently
65+
3. Merge points where work reconvenes
66+
67+
### Phase 4: Plan Generation
68+
69+
Write the final plan to `PLAN.md`. Ensure the plan includes concrete verification steps the agent can run end to end. If the user only wants a plan in chat, provide it inline and mention that it would be written to `PLAN.md`.
70+
71+
## Output Format
72+
73+
The generated plan MUST follow this structure:
74+
75+
```markdown
76+
# [Feature Name] Implementation Plan
77+
78+
## Overview
79+
[2-3 sentence summary of what this implements and why]
80+
81+
## Goals
82+
- [Explicit goal 1]
83+
- [Explicit goal 2]
84+
85+
## Non-Goals
86+
- [What this explicitly does NOT do]
87+
88+
## Assumptions and Constraints
89+
- [Known constraints or assumptions]
90+
91+
## Requirements
92+
93+
### Functional
94+
- [Requirement]
95+
96+
### Non-Functional
97+
- [Performance, reliability, security, compliance]
98+
99+
## Technical Design
100+
101+
### Data Model
102+
[Schema changes, new entities, relationships]
103+
104+
### API Design
105+
[New endpoints, request/response shapes, versioning]
106+
107+
### Architecture
108+
[System diagram in text or mermaid, component interactions]
109+
110+
### UX Flow (if applicable)
111+
[Key screens, loading states, error recovery]
112+
113+
---
114+
115+
## Implementation Plan
116+
117+
### Serial Dependencies (Must Complete First)
118+
119+
These tasks create foundations that other work depends on. Complete in order.
120+
121+
#### Phase 0: [Foundation Name]
122+
**Prerequisite for:** All subsequent phases
123+
124+
| Task | Description | Output |
125+
|------|-------------|--------|
126+
| 0.1 | [Task description] | [Concrete deliverable] |
127+
| 0.2 | [Task description] | [Concrete deliverable] |
128+
129+
---
130+
131+
### Parallel Workstreams
132+
133+
These workstreams can be executed independently after Phase 0.
134+
135+
#### Workstream A: [Name]
136+
**Dependencies:** Phase 0
137+
**Can parallelize with:** Workstreams B, C
138+
139+
| Task | Description | Output |
140+
|------|-------------|--------|
141+
| A.1 | [Task description] | [Concrete deliverable] |
142+
| A.2 | [Task description] | [Concrete deliverable] |
143+
144+
#### Workstream B: [Name]
145+
**Dependencies:** Phase 0
146+
**Can parallelize with:** Workstreams A, C
147+
148+
| Task | Description | Output |
149+
|------|-------------|--------|
150+
| B.1 | [Task description] | [Concrete deliverable] |
151+
152+
---
153+
154+
### Merge Phase
155+
156+
After parallel workstreams complete, these tasks integrate the work.
157+
158+
#### Phase N: Integration
159+
**Dependencies:** Workstreams A, B, C
160+
161+
| Task | Description | Output |
162+
|------|-------------|--------|
163+
| N.1 | [Integration task] | [Concrete deliverable] |
164+
165+
---
166+
167+
## Testing and Validation
168+
169+
- [Unit, integration, end-to-end coverage]
170+
- [Manual test plan if needed]
171+
172+
## Rollout and Migration
173+
174+
- [Feature flags, staged rollout, migration steps]
175+
- [Rollback plan]
176+
177+
## Verification Checklist
178+
179+
- [Exact commands or manual steps the agent can run to verify correctness]
180+
- [Expected outputs or success criteria]
181+
182+
## Risk Assessment
183+
184+
| Risk | Likelihood | Impact | Mitigation |
185+
|------|------------|--------|------------|
186+
| [Risk description] | Low/Med/High | Low/Med/High | [Strategy] |
187+
188+
## Open Questions
189+
190+
- [ ] [Question that still needs resolution]
191+
192+
## Decision Log
193+
194+
| Decision | Rationale | Alternatives Considered |
195+
|----------|-----------|------------------------|
196+
| [Decision made] | [Why] | [What else was considered] |
197+
```
198+
199+
## Interview Flow Example
200+
201+
Round 1: High-Level Architecture
202+
- "The spec mentions a sync engine. Is this push-based (webhooks), pull-based (polling), or event-driven (queue)?"
203+
- "What is the expected data volume and throughput?"
204+
205+
Round 2: Edge Cases
206+
- "If a batch fails mid-run, do we retry the whole batch or resume from a checkpoint?"
207+
- "What happens when source data is deleted but still referenced downstream?"
208+
209+
Round 3: Parallelization
210+
- "Can we process different categories independently, or are there cross-category dependencies?"
211+
- "Is there a natural partition key that allows sharding?"
212+
213+
Round 4: Operational
214+
- "What is the acceptable latency for sync or processing?"
215+
- "How will operators debug failures and what visibility do they need?"
216+
217+
## Key Behaviors
218+
219+
1. Persist until the plan is implementable and verifiable by the agent, but avoid user fatigue by batching questions.
220+
2. Challenge vague answers when they affect design decisions.
221+
3. Identify hidden work and operational overhead.
222+
4. Think about the merge and integration steps early.
223+
5. Summarize understanding and confirm before writing the final plan.
224+
225+
## Completing the Interview
226+
227+
After sufficient rounds of questions:
228+
1. Summarize your understanding back to the user
229+
2. Confirm the parallelization strategy
230+
3. Write the complete plan to the target file
231+
4. Ask if any sections need refinement

‎.agents/skills/create-pr/SKILL.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
name: create-pr
3+
description: Create or update a PR from current branch to main, watch CI, and address feedback
4+
---
5+
The user likes the state of the code.
6+
7+
There are $`git status --porcelain | wc -l | tr -d ' '` uncommitted changes.
8+
The current branch is $`git branch --show-current`.
9+
The target branch is origin/main.
10+
11+
$`git rev-parse --abbrev-ref @{upstream} 2>/dev/null && echo "Upstream branch exists." || echo "There is no upstream branch yet."`
12+
13+
**Existing PR:** $`gh pr view --json number,title,url --jq '"#\(.number): \(.title) - \(.url)"' 2>/dev/null || echo "None"`
14+
15+
The user requested a PR.
16+
17+
Follow these exact steps:
18+
19+
## Phase 1: Review the code
20+
21+
1. Review test coverage
22+
2. Check for silent failures
23+
3. Verify code comments are accurate
24+
4. Review any new types
25+
5. General code review
26+
27+
## Phase 2: Create/Update PR
28+
29+
6. Run `git diff` to review uncommitted changes
30+
7. Commit them. Follow any instructions the user gave you about writing commit messages.
31+
8. Push to origin.
32+
9. Use `git diff origin/main...` to review the full PR diff
33+
10. Check if a PR already exists for this branch:
34+
- **If PR exists**:
35+
- Draft/update the description in a temp file (e.g. `/tmp/pr-body.txt`).
36+
- Update the PR body using the non-deprecated script:
37+
- `./.agents/skills/create-pr/scripts/pr-body-update.sh --file /tmp/pr-body.txt`
38+
- Re-fetch the body with `gh pr view --json body --jq .body` to confirm it changed.
39+
- **If no PR exists**: Use `gh pr create --base main` to create a new PR. Keep the title under 80 characters and the description under five sentences.
40+
41+
The PR description should summarize ALL commits in the PR, not just the latest changes.
42+
43+
## Phase 3: Monitor CI and Address Issues
44+
45+
Note: Keep commands CI-safe and avoid interactive `gh` prompts. Ensure `GH_TOKEN` or `GITHUB_TOKEN` is set in CI.
46+
47+
11. Watch CI status and feedback using the polling script (instead of running `gh` in a loop):
48+
- Run `./.agents/skills/create-pr/scripts/poll-pr.sh --triage-on-change --exit-when-green` (polls every 30s for 10 mins).
49+
- If checks fail, use `gh pr checks` or `gh run list` to find the failing run id, then:
50+
- Fetch the failed check logs using `gh run view <run-id> --log-failed`
51+
- Analyze the failure and fix the issue
52+
- Commit and push the fix
53+
- Continue polling until all checks pass
54+
55+
12. Check for merge conflicts:
56+
- Run `git fetch origin main && git merge origin/main`
57+
- If conflicts exist, resolve them sensibly
58+
- Commit the merge resolution and push
59+
60+
13. Use the polling script output to notice new reviews and comments (avoid direct polling via `gh`):
61+
- If you need a full snapshot, run `./.agents/skills/create-pr/scripts/triage-pr.sh` once.
62+
- If you need full context after the script reports a new item, fetch details once with `gh pr view --comments` or `gh api ...`.
63+
- **Address feedback**:
64+
- For bot reviews, read the review body and any inline comments carefully
65+
- Address comments that are clearly actionable (bug fixes, typos, simple improvements)
66+
- Skip comments that require design decisions or user input
67+
- For addressed feedback, commit fixes with a message referencing the review/comment
68+
69+
## Phase 4: Merge and Cleanup
70+
71+
14. Once CI passes and the PR is approved, ask the user if they want to merge the PR.
72+
73+
15. If the user confirms, merge the PR:
74+
- Use `gh pr merge --squash --delete-branch` to squash-merge and delete the remote branch
75+
76+
16. After successful merge, check if we're in a git worktree:
77+
- Run: `[ "$(git rev-parse --git-common-dir)" != "$(git rev-parse --git-dir)" ]`
78+
- **If in a worktree**: Use the ask user question tool (`request_user_input`) to ask if they want to clean up the worktree. If yes, run `wt remove --yes --force` to remove the worktree and local branch, then switch back to the main worktree.
79+
- **If not in a worktree**: Just switch back to main with `git checkout main && git pull`
80+
81+
## Completion
82+
83+
Report the final PR status to the user, including:
84+
- PR URL
85+
- CI status (passed/merged)
86+
- Any unresolved review comments that need user attention
87+
- Cleanup status (worktree removed or branch switched)
88+
89+
If any step fails in a way you cannot resolve, ask the user for help.

0 commit comments

Comments
 (0)