Perform code optimization and document cleanup (#1)
## Summary - add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers - reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities - clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance ## Notable changes - docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs - new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement - refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code - changelog, development documentation, and CI surface updates ## Test Plan - [ ] `pnpm run check` - [ ] review generated/manifests and skill sync outputs - [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs ## Notes - this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com> Reviewed-on: #1
This commit was merged in pull request #1.
This commit is contained in:
@@ -0,0 +1,31 @@
|
||||
{
|
||||
"$schema": "https://ai-coding-skills.dev/schemas/generated-manifest/v1.json",
|
||||
"generator": "scripts/generate-skills.mjs",
|
||||
"generatedRoot": "skills/create-plan/claude-code",
|
||||
"files": [
|
||||
{
|
||||
"path": "SKILL.md",
|
||||
"kind": "file",
|
||||
"mode": "644",
|
||||
"sha256": "21635cb0342626e5adc568d7cf6d10eb95cdce6fad665b6553718640fd5d51ce"
|
||||
},
|
||||
{
|
||||
"path": "templates/continuation-runbook.md",
|
||||
"kind": "file",
|
||||
"mode": "644",
|
||||
"sha256": "16d72a6d302d22712b1b4cd919bf9d899d6d31775c7183f32c78fe6e28f330d0"
|
||||
},
|
||||
{
|
||||
"path": "templates/milestone-plan.md",
|
||||
"kind": "file",
|
||||
"mode": "644",
|
||||
"sha256": "76700ac603bc13c585cf9de25861be99dc0988df5925f06609ca60a71bee1b6d"
|
||||
},
|
||||
{
|
||||
"path": "templates/story-tracker.md",
|
||||
"kind": "file",
|
||||
"mode": "644",
|
||||
"sha256": "6838b4242765e407d1498402b802b04b59c18b5ca3344aff8c33665bad00f28a"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -3,6 +3,8 @@ name: create-plan
|
||||
description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
|
||||
---
|
||||
|
||||
<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/create-plan/_source/claude-code/ and run `pnpm run sync:pi`. -->
|
||||
|
||||
# Create Plan (Claude Code)
|
||||
|
||||
Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
@@ -12,6 +14,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
This Claude Code variant depends on Superpowers planning skills and explicit sub-skill invocation.
|
||||
|
||||
Required:
|
||||
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- `brainstorming` skill
|
||||
- `writing-plans` skill
|
||||
@@ -23,10 +26,12 @@ If any dependency is missing, stop immediately and return:
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase with exploration agents.
|
||||
- Understand existing patterns and context.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions ONE AT A TIME until user says ready.
|
||||
- Cover scope, constraints, success criteria, dependencies.
|
||||
- Summarize before proceeding.
|
||||
@@ -45,7 +50,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
|
||||
|
||||
1. **Which CLI should review the plan?**
|
||||
@@ -66,11 +70,13 @@ If the user has already specified a reviewer CLI and model (e.g., "create a plan
|
||||
Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
|
||||
|
||||
### Phase 4: Design (REQUIRED SUB-SKILL)
|
||||
|
||||
- Invoke `superpowers:brainstorming` explicitly.
|
||||
- Present 2-3 approaches and recommend one.
|
||||
- Validate design in sections.
|
||||
|
||||
### Phase 5: Plan (REQUIRED SUB-SKILL)
|
||||
|
||||
- Invoke `superpowers:writing-plans` explicitly.
|
||||
- Break into milestones and bite-sized stories (2-5 min each).
|
||||
- Story IDs: `S-{milestone}{sequence}`.
|
||||
@@ -88,6 +94,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
||||
@@ -143,6 +150,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -165,7 +173,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -298,6 +305,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -323,14 +331,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -345,7 +353,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -356,7 +364,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -440,7 +447,7 @@ Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -467,21 +474,25 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 8: Generate Plan Files (MANDATORY - DO NOT SKIP)
|
||||
|
||||
**PLAN MODE CHECK:** If currently in plan mode:
|
||||
|
||||
1. Inform user that plan files cannot be written while in plan mode.
|
||||
2. Instruct user to exit plan mode (approve plan or use ExitPlanMode).
|
||||
3. Proceed with file generation only after exiting plan mode.
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
|
||||
|
||||
1. `original-plan.md` - Copy the plan file from `~/.claude/plans/` as-is.
|
||||
2. `final-transcript.md` - Copy of final planning transcript for reference.
|
||||
3. `milestone-plan.md` - Full specification (template-based).
|
||||
@@ -514,6 +525,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -524,12 +536,14 @@ Rules:
|
||||
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Add commit hash in Notes
|
||||
3. Review pending stories
|
||||
@@ -568,4 +582,5 @@ After completing any story:
|
||||
- [ ] Telegram notification attempted if configured
|
||||
|
||||
## Exit Triggers for Question Phase
|
||||
|
||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/create-plan/_source/claude-code/ and run `pnpm run sync:pi`. -->
|
||||
# Continuation Runbook: [Plan Title]
|
||||
|
||||
## Reference Files (START HERE)
|
||||
@@ -58,15 +59,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -74,16 +79,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -101,16 +109,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/create-plan/_source/claude-code/ and run `pnpm run sync:pi`. -->
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
@@ -8,37 +10,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -48,15 +59,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -68,16 +82,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
@@ -94,6 +111,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/create-plan/_source/claude-code/ and run `pnpm run sync:pi`. -->
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
@@ -46,15 +48,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -63,4 +68,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
Reference in New Issue
Block a user