diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md new file mode 100644 index 0000000..727d6bb --- /dev/null +++ b/skills/implement/SKILL.md @@ -0,0 +1,155 @@ +--- +name: implement +description: Build a detailed todo from an approved plan.md, refine it through annotation, then implement everything without stopping. +disable-model-invocation: true +--- + +## Hard Constraints (every phase, no exceptions) + +- **`plan.md` must exist and contain `**APPROVED**`.** If `$CLAUDE_PROJECT_DIR/.claude/agents/plan.md` does not exist or has no `**APPROVED**`, stop and tell the user to run `/plan-it` first. +- **Read every relevant file in full** — not headers, not signatures, not the first few lines. Do not infer behavior from names alone. +- **Scope**: only files inside `$CLAUDE_PROJECT_DIR`. +- **Every `**note**` must be explicitly resolved** — incorporated, rejected with a reason, or escalated as a question. No note may be silently ignored. +- **During implementation**: no unnecessary comments, no JSDoc/XML doc on internal code, no `any` or unknown types in TypeScript, no `.unwrap()` without justification in Rust. Run typecheck continuously — do not introduce new type errors. + +--- + +## Mode Detection + +Check the state of `$CLAUDE_PROJECT_DIR/.claude/agents/plan.md`: + +| State | Action | +|---|---| +| Does not exist or no `**APPROVED**` | Stop — tell the user to run `/plan-it` first | +| `**APPROVED**` present, no `## Implementation Todo` section | **Todo mode** — run Phase T | +| `## Implementation Todo` exists, contains `**note**` markers | **Todo revision mode** — run Phase TR | +| `## Implementation Todo` exists, contains `**APPROVED**` | **Implementation mode** — run Phase I | +| `## Implementation Todo` exists, no notes, no second approval | Tell the user: "Todo exists but is not approved. Add `**note**` annotations to revise, or add `**APPROVED**` under the todo to begin implementation." | + +--- + +## Todo Mode — Phase T + +Entered when `plan.md` is approved but has no `## Implementation Todo` section yet. + +### T1 — Read the Plan + +Read `plan.md` in full. Read every file listed in the Changes section in full. + +### T2 — Write the Todo + +Append a `## Implementation Todo` section to `plan.md`. Do not modify anything above it. + +The todo must break the plan into phases and each phase into individual, atomic tasks. A task is atomic when it touches one concern in one place and can be marked complete independently. + +```markdown +## Implementation Todo + +> Add `**APPROVED**` below this line when the todo is ready for implementation. + +### Phase 1: +- [ ] +- [ ] + +### Phase 2: +- [ ] +- [ ] Run typecheck — verify no new errors introduced + +### Phase N: Verify +- [ ] Run typecheck — full clean pass +- [ ] Run lint +- [ ] Confirm all tasks above are marked complete +``` + +Every phase must end with a typecheck task. The final phase is always verification. + +### T3 — Stop and Present + +Tell the user: *"Todo written to `.claude/agents/plan.md`. Review it — add `**note**` annotations for anything to revise, or add `**APPROVED**` under the todo header when ready to implement."* + +**Stop. Do not write any code.** + +--- + +## Todo Revision Mode — Phase TR + +Entered when the todo section exists and contains `**note**` markers. + +**Note format:** +``` +--- + +**note** + +--- +``` + +### TR1 — Address Every Note + +For each `**note**` in the todo section: +- **Incorporated** — update the affected tasks and remove the note marker +- **Rejected** — remove the note marker and add a `**note:rejected**` entry explaining why +- **Question** — ask the user before continuing if the note cannot be resolved from the plan and codebase alone + +### TR2 — Rewrite the Todo Section + +Rewrite only the `## Implementation Todo` section with all notes resolved. Do not touch anything above it in `plan.md`. + +### TR3 — Stop and Present + +List every note and its resolution. Then tell the user: *"All notes addressed. Review the updated todo — add more `**note**` annotations to continue revising, or add `**APPROVED**` to begin implementation."* + +**Stop. Do not write any code.** + +--- + +## Implementation Mode — Phase I + +Entered when the todo section exists and contains `**APPROVED**`. + +### I1 — Read Everything + +Read `plan.md` in full. Read every file that will be changed in full before writing a single line of code. + +### I2 — Implement + +Work through every task in the todo, phase by phase, in order. + +**For each task:** +1. Implement the change +2. Run typecheck immediately after — fix any new errors before moving on +3. Mark the task complete in `plan.md`: `- [x]` + +**Do not stop between tasks.** Do not stop between phases. Complete the entire todo without pausing unless a genuine blocker is encountered (a task is impossible as written, or a new error cannot be resolved). If blocked, describe the blocker and ask — then continue with remaining tasks while waiting. + +**Code quality during implementation:** +- No unnecessary comments or section dividers +- No JSDoc or XML doc on internal/private code +- TypeScript: no `any`, no implicit `unknown` — all types must be explicit and correct +- Rust: no `.unwrap()` without a documented invariant +- C#: no empty catch blocks, no `throw ex` — use `throw` to preserve stack trace +- Honor the existing code style in every file touched — match naming, formatting, and patterns already present + +**TypeScript / SPFx specifics:** +- Use `.then().catch()` — never `async`/`await` +- `.catch()` must use `LoggingService.Instance.Log` if present, otherwise the project's existing logging pattern + +**C# specifics:** +- Wrap `IDisposable` in `using` / `using var` +- Batch `ExecuteQuery` calls — do not scatter them +- Prefer synchronous code unless the existing code is already async + +**Rust specifics:** +- Propagate errors with `?` — not `.unwrap()` in non-test code +- No `unsafe` without justification + +### I3 — Final Verify + +After all tasks are marked complete: +- Run typecheck — must be clean +- Run lint +- Confirm every task in the todo is marked `- [x]` + +### I4 — Report + +Tell the user what was implemented, phase by phase. Flag any deviations from the plan (tasks that had to be adapted) and explain why. diff --git a/skills/plan-it/SKILL.md b/skills/plan-it/SKILL.md new file mode 100644 index 0000000..d1a19f2 --- /dev/null +++ b/skills/plan-it/SKILL.md @@ -0,0 +1,158 @@ +--- +name: plan-it +description: Read research.md and write a detailed implementation plan to plan.md. Annotation cycle with user until APPROVED. Requires research to have been run first. +argument-hint: "[what to build, change, or fix]" +disable-model-invocation: true +--- + +Plan the following: **$ARGUMENTS** + +## Hard Constraints (every phase, no exceptions) + +- **`research.md` is required.** If `$CLAUDE_PROJECT_DIR/.claude/agents/research.md` does not exist, stop immediately and tell the user to run `/research` first. +- **No code changes.** The only file you may write is `$CLAUDE_PROJECT_DIR/.claude/agents/plan.md`. +- **Read every relevant file in full** — not headers, not signatures, not the first few lines. Do not infer behavior from names alone. +- **Scope**: only files inside `$CLAUDE_PROJECT_DIR`. +- **Every `**note**` must be explicitly resolved** — incorporated, rejected with a reason, or escalated as a question. No note may be silently ignored. + +--- + +## Mode Detection + +Before doing anything else, check the state of `$CLAUDE_PROJECT_DIR/.claude/agents/plan.md`: + +| State | Action | +|---|---| +| Does not exist | **Initial mode** — run Phases 1–5 | +| Exists, contains `**APPROVED**` | Stop — tell the user the plan is approved and to run `/implement` | +| Exists, contains `**note**` markers | **Revision mode** — run Phase R | +| Exists, no notes, no approval | Tell the user: "plan.md exists but has no notes and is not approved. Add `**APPROVED**` to proceed to implementation, or add `**note**` annotations for revision." | + +--- + +## Initial Mode — Phases 1–5 + +### Phase 1 — Load Research + +Read `$CLAUDE_PROJECT_DIR/.claude/agents/research.md` in full. Everything in the plan must be grounded in what the research established. + +If the research scope does not cover the area this plan needs to change, flag it and ask the user whether to proceed with partial context or run `/research` on the missing area first. + +### Phase 2 — Clarify Scope + +Parse the argument: +- What is the goal? +- What is explicitly in scope? +- What is explicitly out of scope? + +If the argument is ambiguous, ask before proceeding. Do not plan on assumptions. + +### Phase 3 — Investigate Current State + +Read every file relevant to the planned change in full. The research was broad — this reading is targeted to the specific change. + +**Stack-specific things to consider:** + +*TypeScript / SPFx* +- Where does this touch the webpart/extension lifecycle? +- Which PnPjs calls are involved — are they already batched? +- How does existing error handling work in the affected files? + +*C# / CSOM* +- Which `ClientContext` operations are affected — will batching change? +- Is there existing async code in this area, or is it synchronous? +- What exception handling patterns are already in place? + +*Rust* +- Will the change affect the `Result` type of any public functions? +- Are there ownership or lifetime constraints the change must work within? +- Does this touch any `async` code paths? + +### Phase 4 — Write plan.md + +Write to `$CLAUDE_PROJECT_DIR/.claude/agents/plan.md`: + +```markdown +# Plan: + +## Goal + + +## Approach + + +## Changes + +### `path/to/file.ext` +**Type**: modify / new file / delete +**What changes**: + +## Order of Changes +1. `file` — reason +2. `file` — depends on #1 + +## New Files +| File | Purpose | +|---|---| +| `path/to/new/file` | what it will contain | + +*(Remove section if no new files)* + +## Out of Scope + + +## Risks + + +## Open Questions + +``` + +### Phase 5 — Stop and Present + +Summarize to the user: +- Number of files changing +- Approach in one sentence +- Any open questions + +Then tell the user: *"Plan written to `.claude/agents/plan.md`. Review it — add `**note**` annotations for anything to revise, or add `**APPROVED**` when ready to move to implementation."* + +**Stop. Do not proceed.** + +--- + +## Revision Mode — Phase R + +Entered when `plan.md` exists and contains `**note**` markers. + +**Note format written by the user:** +``` +--- + +**note** + +--- +``` + +### R1 — Read Everything + +Read `research.md` and the current `plan.md` in full. Read any project files referenced in the notes or needed to address them. + +### R2 — Address Every Note + +For each `**note**` marker in `plan.md`, explicitly resolve it: +- **Incorporated** — update the relevant section of the plan and remove the note marker +- **Rejected** — remove the note marker and add a `**note:rejected**` entry explaining why the change would be wrong or out of scope +- **Question** — if the note cannot be resolved without more information, ask the user before continuing + +No note may remain unaddressed when writing the updated plan. + +### R3 — Rewrite plan.md + +Write the updated `plan.md` with all notes resolved. The plan must remain complete — do not leave gaps where notes were removed. + +### R4 — Stop and Present + +List every note and how it was resolved (incorporated / rejected / answered). Then tell the user: *"All notes addressed. Review the updated `.claude/agents/plan.md` — add more `**note**` annotations to continue revising, or add `**APPROVED**` when ready."* + +**Stop. Do not proceed.** diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md new file mode 100644 index 0000000..e7be4ed --- /dev/null +++ b/skills/research/SKILL.md @@ -0,0 +1,209 @@ +--- +name: research +description: Deeply read and understand a project, feature, or system and write a validated research report +argument-hint: "[describe what to research — full project, a specific feature/system, or a bug hunt]" +disable-model-invocation: true +--- + +Research the following: **$ARGUMENTS** + +## Hard Constraints (every phase, no exceptions) + +- **Read every relevant file in full** — not headers, not signatures, not the first 20 lines. Read the actual implementation. Do not infer behavior from names alone. +- **Never modify any code or project files.** The only file you may write is `$CLAUDE_PROJECT_DIR/.claude/agents/research.md`. +- **Scope**: only files inside `$CLAUDE_PROJECT_DIR`. +- **The research.md output is a review surface** — write it so the user can read it and verify you understood the system correctly before any planning begins. Not a data dump. Structured, referenced, readable. + +--- + +## Phase 1 — Determine Mode and Scope + +Parse the argument and determine which mode applies: + +| Mode | Signals in argument | +|---|---| +| **General** | "full project", "this folder", "everything", "how this works", no specific subject | +| **Feature** | names a specific system, flow, module, or feature | +| **Bug Hunt** | mentions bugs, issues, incorrect behavior, or asks to find problems | + +If the mode or scope is ambiguous, ask before proceeding. + +--- + +## Phase 2 — Discover + +Identify all files relevant to the scope. Do not read them yet — build the list first. + +**For General mode:** +- List all source files by directory +- Identify entry points (program start, webpart init, main modules, controllers) +- Identify config, manifest, and dependency files + +**For Feature / Bug Hunt mode:** +- Start from the named system or entry point +- Trace all files touched by this flow: callers, callees, shared utilities, config, types +- Grep for the key identifiers to ensure no related files are missed +- Build a complete file list before reading any of them + +--- + +## Phase 3 — Read Deeply + +Read every file in the list from Phase 2 **in full**. For each file, understand: +- What it does and why it exists +- How it fits into the broader system +- What patterns and conventions it uses +- What it depends on and what depends on it + +**Stack-specific things to look for while reading:** + +*TypeScript / SPFx* +- Webpart and extension lifecycle methods (`onInit`, `render`, `onDispose`) +- How PnPjs is set up and used — `sp.setup()` location, batch operations +- `.then().catch()` chains — are errors handled or swallowed? +- How SharePoint context (`this.context`) flows through the code + +*C# / CSOM* +- `ClientContext` creation, use, and disposal — is it wrapped in `using`? +- Where `ExecuteQuery` / `ExecuteQueryAsync` is called — are calls batched or scattered? +- Exception handling — is context added, or are errors swallowed? +- `async`/`await` usage — is it introduced unnecessarily, or is it pre-existing? + +*Rust* +- Error propagation — `?`, `.unwrap()`, `.expect()` — where and why +- Ownership and borrowing patterns — any obvious clones or lifetime workarounds? +- `async` runtime in use, if any — how tasks are spawned and awaited +- `unsafe` blocks — are they present, and are they justified? + +--- + +## Phase 4 — Analyze + +**General mode:** +- Map the architecture: how layers / modules relate +- Identify the main data flows through the system +- Note patterns and conventions used consistently across the codebase +- Flag anything inconsistent, surprising, or worth noting + +**Feature mode:** +- Trace the complete flow end-to-end with file:line references at each step +- Identify all inputs, outputs, side effects, and error paths +- Note edge cases and how (or whether) they are handled +- Flag anything that looks fragile, overly complex, or undocumented + +**Bug Hunt mode:** +- Trace every code path in scope — not just the happy path +- For each path, check against the bug patterns relevant to the stack (see Phase 3) +- A path is done when you have read every branch, every error handler, and every caller +- Do not stop until no unexamined paths remain in scope +- For each bug found, record: location, evidence, how it manifests, severity + +--- + +## Phase 5 — Write research.md + +Write to `$CLAUDE_PROJECT_DIR/.claude/agents/research.md` using the template for the detected mode. Use `file:line` references throughout. Include code snippets as evidence where relevant — especially for bugs and non-obvious patterns. + +--- + +### Template: General + +```markdown +# Research: Full Project + +## Overview + + +## Architecture + + +## Entry Points + + +## Key Files +| File | Purpose | +|---|---| +| `path/to/file` | what it does | + +## Data Flow + + +## Patterns & Conventions + + +## Dependencies + + +## Surprises / Points of Interest + + +## Open Questions + +``` + +--- + +### Template: Feature + +```markdown +# Research: [Feature / System Name] + +## Overview + + +## Files Involved +| File | Role in this feature | +|---|---| +| `path/to/file` | what it contributes | + +## Flow Walkthrough + + +1. `file:line` — +2. `file:line` — +... + +## Error Paths + + +## Edge Cases + + +## Patterns & Conventions + + +## Dependencies + + +## Open Questions + +``` + +--- + +### Template: Bug Hunt + +```markdown +# Research: Bug Hunt — [System / Flow Name] + +## Scope + + +## Code Paths Traced +- [ ] `file:line` — +- [ ] `file:line` — + +## Bugs Found + +### Bug N: +- **Location**: `file:line` +- **Evidence**: +- **How it manifests**: +- **Severity**: + +## Clean Paths + + +## Open Questions + +```