diff --git a/.claude/skills/apply-pr-feedback/SKILL.md b/.claude/skills/apply-pr-feedback/SKILL.md deleted file mode 100644 index 77b186c..0000000 --- a/.claude/skills/apply-pr-feedback/SKILL.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -name: apply-pr-feedback -description: "Automated PR review loop: fetches all PR comments, checks the last one to determine state, evaluates and fixes codex findings, pushes, re-triggers review, and repeats until clean — then squash-merges." -argument-hint: "[pr-number-or-url]" ---- - -# Apply PR Feedback - -Deterministic loop that processes codex review feedback on a PR until clean, then merges. - -## Inputs - -- **PR number or URL** — optional. If not provided, detect from the current Graphite branch (`gt ls` or `gh pr list --head `). - -No manual copy-paste of feedback is needed — the skill reads comments directly from the PR. - -## Setup - -1. Determine the PR number (from argument or current branch). -2. Determine the repo owner/name from `git remote get-url origin`. - -## Step 1: Get All Comments - -Fetch all comments on the PR (both issue comments and PR review comments are visible here): -```bash -gh api repos/{owner}/{repo}/issues/{pr}/comments \ - --jq '[.[] | {id, user: .user.login, body: .body, created_at}] | sort_by(.created_at)' -``` - -Also fetch PR reviews (codex sometimes posts as a PR review instead of an issue comment): -```bash -gh api repos/{owner}/{repo}/pulls/{pr}/reviews \ - --jq '[.[] | {id, user: .user.login, body: .body, submitted_at}] | sort_by(.submitted_at)' -``` - -Combine both lists and sort by timestamp. Identify the **last comment/review** across both. - -## Step 2: Check the Last Comment - -Look at the last comment/review and branch: - -### (a) Last comment contains `@codex review` - -Review is still pending. Sleep 60 seconds, then go back to **Step 1**. - -### (b) Last comment/review is from `chatgpt-codex-connector[bot]` - -Check if it indicates a clean review or has findings: - -- **Clean review** — the body contains "Didn't find any major issues" or similar pass message → go to **Step 8**. -- **Has findings** — codex posted inline review comments → go to **Step 3**. - -To check for inline findings: -```bash -gh api repos/{owner}/{repo}/pulls/{pr}/comments \ - --jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]")]' -``` -Filter to only unresolved comments (check against resolved threads). If there are unresolved codex comments, proceed to **Step 3**. If all are resolved (or there are none), treat as clean → go to **Step 8**. - -### (c) Last comment is something else (e.g., Greptile, a human) - -Ignore it. Look at the comment before it and repeat this check. Walk backwards through comments until you find either `@codex review` or a `chatgpt-codex-connector[bot]` response. - -## Step 3: Evaluate Findings - -For each unresolved codex inline comment: - -1. Read the referenced file and line range with full surrounding context. -2. Evaluate the feedback against the actual code: - - **Valid** — real issue (bug, safety concern, spec violation, missing edge case) - - **Improvement** — better approach, correct but not strictly a bug - - **False positive** — problem does not actually exist in the code - -3. Report assessment: - ```text - [file:lines] — - Reason: <1-2 sentence explanation> - ``` - -4. If **valid** or **improvement**, apply the fix immediately. -5. If **false positive**, reply to the comment with a brief reason explaining why. - -## Step 4: Resolve PR Conversations - -After evaluating ALL comments and applying all fixes, resolve each review thread: - -To resolve a review thread, use the GraphQL API. First fetch thread IDs: -```bash -gh api graphql -f query=' - query { - repository(owner: "", name: "") { - pullRequest(number: ) { - reviewThreads(last: 50) { - nodes { id isResolved comments(first: 1) { nodes { body author { login } } } } - } - } - } - } -' -``` - -Then resolve each unresolved codex thread: -```bash -gh api graphql -f query=' - mutation { - resolveReviewThread(input: {threadId: ""}) { - thread { isResolved } - } - } -' -``` - -**Important:** `resolveReviewThread` requires a `PullRequestReviewThread` ID (starts with `PRRT_`), not a review comment ID. Match threads to comments by the first comment body and author. - -## Step 5: Run Acceptance Checks - -1. Run the repository acceptance criteria: - - Build commands (including no_std if applicable). - - Linter / clippy with warnings as errors. - - Formatter check. - - Full test suite. -2. If any check fails, fix the issue and rerun until passing. - -## Step 6: Push Changes - -Once all checks pass: -```bash -git add -gt modify -gt submit -``` - -Report summary: -```text -| File:Lines | Assessment | Action | -|---|---|---| -| file.rs:10-15 | Valid | Brief description of fix applied | -| file.rs:42-44 | False positive | Reason (no change) | - -Checks passed: -- -- - -Pushed via: gt modify + gt submit -``` - -## Step 7: Trigger Review and Loop - -```bash -gh pr comment {pr-number} --body "@codex review" -sleep 60 -``` - -Go back to **Step 1**. - -## Step 8: Merge PR - -Codex review passed with no issues. Ask the user: "Codex review passed. Shall I squash-merge this PR?" - -If the user accepts: -```bash -gh pr merge {pr-number} --squash --delete-branch -``` - -Report the merge result. - -## Rules - -- Never push before all acceptance checks pass. -- Keep fixes minimal and targeted to the feedback. -- Do not use `git commit` directly — use `gt modify` to amend into the existing branch commit. -- If a fix introduces a test failure elsewhere, investigate and fix before pushing. -- If feedback is ambiguous, ask the user to clarify before making changes. -- Only process comments from `chatgpt-codex-connector[bot]` — ignore other reviewers. -- Push autonomously — no user confirmation needed between loop iterations. -- When waiting for review, poll every 60 seconds — do not busy-loop. diff --git a/.claude/skills/create-plan-linear/SKILL.md b/.claude/skills/create-plan-linear/SKILL.md index 8da1925..27250f9 100644 --- a/.claude/skills/create-plan-linear/SKILL.md +++ b/.claude/skills/create-plan-linear/SKILL.md @@ -1,6 +1,6 @@ --- name: create-plan-linear -description: "Create detailed implementation plans with codebase research and, after explicit user approval, publish the approved phased plan to Linear by creating a project under a chosen initiative plus phase and subphase issues assigned to Timur Guvenkaya." +description: "Create detailed implementation plans with codebase research and, after explicit user approval, publish the approved phased plan to Linear by creating a project under a chosen initiative plus phase and subphase issues." argument-hint: "[ticket-or-file-path]" --- @@ -128,8 +128,9 @@ Create a detailed implementation plan first. Only after explicit user approval, - Set `summary` to a concise one-line overview from the plan. 4. Resolve assignee -- Resolve Timur via `mcp__linear__get_user` with query `timur guvenkaya`. -- If no exact match is found, ask the user before assigning to another user. +- Ask the user who should be assigned to the issues. +- Resolve the provided name via `mcp__linear__get_user`. +- If multiple matches or no match, list results and ask the user to confirm. 5. Prepare labels and severity - Derive labels from phase scope (for example: `consensus`, `execution`, `networking`, `docs`, `testing`). @@ -148,7 +149,7 @@ Create a detailed implementation plan first. Only after explicit user approval, - Create one Linear issue per top-level phase under the created project. - Set issue title to the phase title. - Set issue description to the phase plan content (scope, changes, and success criteria). -- Assign each issue to Timur. +- Assign each issue to the resolved assignee. - Add derived labels, severity label, and priority. 7. Create subphase sub-issues diff --git a/.claude/skills/create-plan/SKILL.md b/.claude/skills/create-plan/SKILL.md deleted file mode 100644 index b7a6190..0000000 --- a/.claude/skills/create-plan/SKILL.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -name: create-plan -description: "Create detailed implementation plans with codebase research, phased steps, file:line references, and verification criteria. Use when asked to plan, spec, or design a feature." -argument-hint: "[ticket-or-file-path]" ---- - -# Create Plan - -Creates detailed implementation plans and technical specifications. - -## Intake - -- If a ticket or file path is provided as `$ARGUMENTS`, read it fully first. -- If no inputs are provided, ask for: task/ticket, constraints, and related references or links. -- Ask only questions that cannot be resolved by code or docs. - -## Research - -- Read all mentioned files completely; avoid partial reads. -- Use Grep/Glob for quick targeted lookups. -- Spawn parallel sub-agents via the Task tool for deeper investigation: - - **`codebase-analyzer`** — understand how specific components work (data flow, logic, patterns) - - **`codebase-pattern-finder`** — find similar implementations or conventions to model after - - **`thoughts-analyzer`** — deep-dive on research docs in `thoughts/` for prior decisions - - **`thoughts-locator`** — discover relevant documents in `thoughts/` directory - - **`web-search-researcher`** — research external APIs, libraries, or technologies -- Discover and use MCP servers for additional context: - - Call `list_mcp_resources` and `list_mcp_resource_templates`. - - Read relevant resources (tickets, docs, schemas, runbooks). -- Spawn multiple sub-agents in parallel for efficiency; wait for all to complete before synthesizing. - -## Synthesis - -- Summarize current state with file:line references and constraints. -- If the user corrects something, re-check sources before proceeding. - -## Plan Development - -- Propose design options with pros/cons and align on approach. -- Present a phase outline and confirm ordering. -- Write the detailed plan using the template below. -- Keep automated and manual verification separate. -- Use project-standard commands for build/test/lint/docs. - -## Completion Rules - -- Do not finalize the plan with open questions. -- Make decisions explicit; verify assumptions with sources. - -## Output Location - -- Save the plan to `/thoughts/shared/plans/-.md`. -- If the repo root is ambiguous, detect it from the current working directory or ask. -- Use the current date in `YYYY-MM-DD` format (e.g., `2025-01-30-auth-refactor.md`). - -## Template - -```markdown -# [Feature/Task Name] Implementation Plan - -## Overview -[What we are implementing and why] - -## Current State Analysis -[What exists now, what is missing, constraints; include file:line references] - -## Desired End State -[What "done" looks like and how to verify it] - -## What We Are Not Doing -[Explicit out-of-scope list] - -## Implementation Approach -[High-level strategy and rationale] - -## Phase 1: [Descriptive Name] -[What this phase accomplishes] - -### Changes Required -- File: `path/to/file.ext` (file:line) -- Summary of edits -```[language] -# Pseudocode or key snippets if helpful -``` - -### Success Criteria - -#### Automated Verification -- [ ] Command or test that must pass - -#### Manual Verification -- [ ] Human validation steps - -**Implementation Note**: After completing this phase and automated verification, pause for manual confirmation before proceeding. - ---- - -## Phase 2: [Descriptive Name] -[Repeat structure] - ---- - -## Testing Strategy -- Unit tests -- Integration tests -- Manual testing steps - -## Performance Considerations -[Implications and mitigations] - -## Migration Notes -[If applicable] - -## References -- Ticket or request reference -- Related research docs -- Similar implementations (file:line) -``` diff --git a/.claude/skills/implement-plan-linear/SKILL.md b/.claude/skills/implement-plan-linear/SKILL.md index 38c24ab..2033c6d 100644 --- a/.claude/skills/implement-plan-linear/SKILL.md +++ b/.claude/skills/implement-plan-linear/SKILL.md @@ -93,30 +93,50 @@ Please run the manual verification steps for this phase and confirm when complet ## Graphite Workflow -After manual confirmation for a phase, run these three steps in order: +Phases form a **Graphite stack** — each phase branch stacks on top of the previous one. The stack is created incrementally: phase 1 branches off trunk, phase 2 branches off phase 1, and so on. The entire stack is merged together after all phases are complete and reviewed. -1. **Sync trunk and clean up merged branches:** - - `gt sync` — pulls latest trunk, restacks open branches, prompts to delete merged branches (accept deletions when prompted). +After manual confirmation for a phase, run these steps in order: + +1. **Sync trunk and restack:** + - `gt sync` — pulls latest trunk, restacks open branches, accepts deletion of merged branches. Safe to run whether on trunk or on an existing stack branch. 2. **Create the branch with all changes committed:** - Fetch the branch name from the Linear issue via `mcp__linear__get_issue` (the `gitBranchName` field). - - `gt create -am "" ` - - This stages all changes, commits them, and creates a new Graphite branch in one step. The branch name MUST be the one from the Linear issue (e.g. `feature/eng-1242`). + - `gt create -am "(/): phase - ()" ` + - `gt create` stacks on whatever branch you are currently on — trunk for phase 1, the previous phase's branch for phase 2+. + - Commit message format: + - ``: conventional commit type derived from the phase's intent: + - `feat` — new functionality, new API surface, new exports + - `fix` — bug fixes, correcting broken behavior + - `refactor` — restructuring without behavior change + - `test` — adding/updating tests only + - `docs` — documentation, README, comments only + - `chore` — build config, CI, package metadata, tooling + - ``: package folder name under `packages/` (e.g. `pq-jws`, `pq-oid`, `pq-key-encoder`) + - ``: language folder under the package (`ts`, `rust`, or `python`) + - ``: phase number from the plan + - ``: concise summary of the phase scope + - ``: Linear issue key provided at invocation (e.g. `ENG-1640`) + - Determine `` by reading the phase title and scope from the plan — pick the type that best describes the primary intent of the phase. + - Examples: + - `feat(pq-jws/ts): phase 1 - define public contracts (ENG-1640)` + - `test(pq-jws/ts): phase 4 - comprehensive test suite (ENG-1643)` + - `fix(pq-oid/rust): phase 2 - correct DER length encoding (ENG-1500)` 3. **Submit and publish the stack:** - - `gt submit --publish` + - `gt submit --publish` — pushes all branches in the stack and creates/updates PRs for each. 4. **Trigger automated review:** - - After the PR is created/updated, post a review trigger comment: - `gh pr comment --body "@codex review"` Rules: -- Always run `gt sync` first to avoid "already merged" errors blocking submit. +- Always run `gt sync` before `gt create` — it is safe on stack branches and keeps the stack rebased on latest trunk. - The branch name comes from Linear's `gitBranchName` field — never invent branch names. - `gt create -am` handles staging, committing, and branch creation — do not use `git add` or `git commit` separately. -- Use commit messages tied to phase scope, not generic text. +- Commit message must follow: `(/): phase - ()` — derive type from the phase intent, package/language from the plan path, phase number from the plan, and issue key from the input. - Do not run `gt submit --publish` before manual confirmation. +- Do **not** merge individual phase PRs — the entire stack is merged together after all phases are complete. - If a `gt` command fails, report the exact command and error output. ## When to Use Sub-agents diff --git a/.claude/skills/implement-plan/SKILL.md b/.claude/skills/implement-plan/SKILL.md deleted file mode 100644 index 65fac15..0000000 --- a/.claude/skills/implement-plan/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: implement-plan -description: "Implements approved technical plans from thoughts/shared/plans with phased execution and verification. Use when asked to implement or carry out a plan file." -argument-hint: "[plan-file-path] [linear-issue-key (optional)]" ---- - -# Implement Plan - -Implements an approved technical plan from `thoughts/shared/plans/` with phased execution and verification. - -## Getting Started - -- If a plan path is provided as `$ARGUMENTS`, read the plan completely and check for any existing checkmarks (`- [x]`). -- If a Linear issue key is provided (e.g. `ENG-1241`), resolve it via `mcp__linear-server__get_issue` and use it for progress updates throughout execution. -- Read the original ticket and all files mentioned in the plan. -- Read files fully (no limit/offset); ensure complete context. -- Think through how the pieces fit together before making changes. -- Create a todo list to track progress. -- Start implementing once the scope is clear. -- If no plan path is provided, ask for one. - -## Implementation Philosophy - -- Follow the plan's intent while adapting to what you find. -- Implement each phase fully before moving to the next. -- Verify changes make sense in the broader codebase context. -- Update checkboxes in the plan as sections are completed. - -If you encounter a mismatch between plan and codebase: - -``` -Issue in Phase [N]: -Expected: [what the plan says] -Found: [actual situation] -Why this matters: [explanation] - -How should I proceed? -``` - -## Verification Approach - -After implementing a phase: - -- Run the success criteria checks (usually `make check test` covers everything). -- Fix any issues before proceeding. -- Update progress in both the plan and your todos. -- Check off completed items in the plan file itself. -- Pause for human verification after automated checks unless explicitly instructed to execute multiple phases. - -Manual verification pause format: - -``` -Phase [N] Complete - Ready for Manual Verification - -Automated verification passed: -- [List automated checks that passed] - -Please perform the manual verification steps listed in the plan: -- [List manual verification items from the plan] - -Let me know when manual testing is complete so I can proceed to Phase [N+1]. -``` - -Do not check off manual testing items until the user confirms completion. - -## Linear Progress Updates (when issue key provided) - -When a Linear issue key is provided, keep the issue synced as work progresses: - -- **After automated checks pass for a phase**: - - Update the Linear issue description to check off the corresponding checkboxes (e.g. `- [ ]` → `- [x]`) using `mcp__linear-server__update_issue` with the updated description markdown. - - Post a concise progress comment via `mcp__linear-server__create_comment` summarizing completed scope, acceptance commands run, and results. - - Move the issue to in-review status via `mcp__linear-server__update_issue`. - - If the correct status name is unclear, query via `mcp__linear-server__list_issue_statuses` and ask before changing state. -- **After manual verification is confirmed**: update the description to check off manual verification checkboxes and post a confirming comment. - -Rules: -- Always read the current issue description before updating it to avoid overwriting other changes. -- Only check off items in the description that have actually been verified to pass. -- Do not change issue status before automated checks pass. - -## If You Get Stuck - -- Re-read all relevant code before making assumptions. -- Consider whether the codebase evolved since the plan was written. -- Present the mismatch clearly and ask for guidance. -- Spawn sub-agents via the Task tool for targeted investigation: - - **`codebase-analyzer`** — trace how a specific component works when you need deeper understanding - - **`codebase-pattern-finder`** — find existing patterns to follow when implementing something unfamiliar - - **`web-search-researcher`** — research external APIs, unfamiliar errors, or version-specific docs -- Keep sub-agent usage focused; provide specific questions and file paths when spawning them. - -## Resuming Work - -- If the plan has existing checkmarks, trust completed work and start from the first unchecked item. -- Verify previous work only if something seems off. -- Maintain forward momentum toward the end goal. diff --git a/.claude/skills/iterate-plan-linear/SKILL.md b/.claude/skills/iterate-plan-linear/SKILL.md deleted file mode 100644 index f047e38..0000000 --- a/.claude/skills/iterate-plan-linear/SKILL.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -name: iterate-plan-linear -description: "Iterate and refine existing implementation plan files using user feedback, then after explicit approval update the related Linear project and phase/subphase issues with the revised plan content. Use when asked to revise a plan and keep Linear tracking artifacts synchronized." -argument-hint: "[plan-file-path] [feedback]" ---- - -# Iterate Plan + Linear Sync - -Revise an existing plan first. After user approval, sync the approved revision to Linear project and issue records. - -## Input Handling - -- Identify plan path and requested feedback from `$ARGUMENTS`. -- If the plan path is missing, ask for it and stop. -- If feedback is missing, ask what to change and stop. -- Capture Linear context early when available: - - project identifier or name - - team - - initiative - - existing issue mapping (phase -> issue ID) - -## Step 1: Read and Understand Current Plan - -1. Read the entire plan file. - - Use the Read tool with no range for the initial read. - - If the file exceeds the default window, read additional ranges until complete. -2. Extract: - - plan title - - top-level phases - - subphases - - success criteria and scope boundaries -3. Parse requested edits and determine whether codebase research is needed. - -## Step 2: Research Only When Needed - -- Use Grep/Glob for quick targeted lookups. -- Spawn parallel sub-agents via the Task tool for deeper investigation: - - **`codebase-analyzer`** — understand how specific components work - - **`codebase-pattern-finder`** — find existing patterns or conventions to follow - - **`thoughts-analyzer`** — extract insights from prior research in `thoughts/` - - **`thoughts-locator`** — discover relevant documents in `thoughts/` - - **`web-search-researcher`** — research external APIs, libraries, or best practices -- Read identified files fully and capture file:line references for any new claims added to the plan. -- Run independent research tasks in parallel when possible. -- Skip external research unless the change depends on external, time-sensitive information. - -## Step 3: Confirm Change Intent Before Editing - -Summarize: -- requested changes -- relevant constraints discovered -- exact edits you intend to make - -Ask for confirmation before modifying the plan. - -## Step 4: Update the Plan Surgically - -- Preserve existing structure unless the user explicitly requests structural changes. -- Keep edits precise; avoid full rewrites. -- Keep automated and manual verification sections separate. -- If scope changes, update out-of-scope sections and affected phases. -- Keep any file:line references accurate. -- Ensure consistency: - - If adding a new phase, follow the existing pattern. - - If modifying scope, update the "What We Are Not Doing" section. - - If changing approach, update "Implementation Approach". - -## Step 5: Present Updates - -Present the updates before requesting Linear sync approval: - -``` -I've updated the plan at `thoughts/shared/plans/[filename].md` - -Changes made: -- [Specific change 1] -- [Specific change 2] - -The updated plan now: -- [Key improvement] -- [Another improvement] - -Would you like any further adjustments, or approve syncing these revisions to Linear? -``` - -Be ready to iterate further based on feedback. - -## Step 6: Approval Gate for Linear Sync (Mandatory) - -After plan edits are finalized, pause and ask for explicit approval, for example: - -`I updated . Approve syncing these revisions to Linear project/issues?` - -Rules: -- Never create or update Linear records before explicit approval. -- If the user requests more plan changes, iterate again and ask for approval again. - -## Step 7: Sync Approved Plan Changes to Linear - -Run only after approval. - -1. Resolve target project -- Prefer a user-provided project ID or project name. -- If missing, infer from prior sync context in the plan or recent conversation. -- If ambiguous, ask the user to choose; do not guess. - -2. Resolve team and assignee -- Use the provided team, or infer from the existing project. -- Resolve assignee via `mcp__linear__get_user` with query `timur guvenkaya`. -- If no exact match is found, ask before assigning alternatives. - -3. Update project record -- Update the Linear project summary and description with the approved plan via `mcp__linear__create_project` or the appropriate update MCP call. -- Keep wording grounded in the approved plan; do not add new scope. - -4. Prepare labels and severity -- Derive labels from phase scope (for example: `consensus`, `execution`, `networking`, `docs`, `testing`). -- For each required label: - - Check existing labels via `mcp__linear__list_issue_labels`. - - Create missing labels via `mcp__linear__create_issue_label`. -- Default severity mapping: - - `critical` -> priority `1`, label `severity:critical` - - `high` -> priority `2`, label `severity:high` - - `medium` -> priority `3`, label `severity:medium` - - `low` -> priority `4`, label `severity:low` -- If severity is unclear from the plan, default to `medium`. - -5. Sync phase issues -- Map each top-level phase to an existing issue (prefer explicit IDs; otherwise exact-title match inside the project). -- Update matched issues with revised scope, success criteria, labels, and priority. -- Create missing phase issues when no reliable match exists. -- Assign each issue to Timur. - -6. Sync subphase issues -- For each subphase, update or create a child issue under the parent phase issue using `parentId`. -- Keep child issue descriptions aligned to the updated plan text. - -7. Handle removed or renamed phases safely -- Do not auto-close or delete unmatched issues. -- Present unmatched items and ask whether to close, rename, or leave unchanged. - -8. Return sync report -- Report the project updated. -- List issues created, updated, and unmatched. -- Call out assumptions and any clarifications requested. - -## Important Guidelines - -### Be Skeptical -- Don't blindly accept change requests that seem problematic. -- Question vague feedback and ask for clarification. -- Verify feasibility with code research. -- Point out conflicts with existing phases. - -### Be Surgical -- Make precise edits, not wholesale rewrites. -- Preserve content that doesn't need changing. -- Research only what the specific changes require. - -### No Open Questions -- If the requested change raises questions, ask. -- Do not update the plan with unresolved issues. - -## Execution Rules - -- Never skip the approval gate. -- Never mutate Linear with ambiguous project, team, or assignee selection. -- Prefer deterministic mappings from plan phase names to issue records. -- Keep output auditable by including identifiers for all updated and created records. diff --git a/.claude/skills/iterate-plan/SKILL.md b/.claude/skills/iterate-plan/SKILL.md deleted file mode 100644 index 190fbd4..0000000 --- a/.claude/skills/iterate-plan/SKILL.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -name: iterate-plan -description: "Iterates on existing implementation plans using user feedback, updating phases, scope, and verification criteria. Use when asked to revise, adjust, or refine a plan file." -argument-hint: "[plan-file-path] [feedback]" ---- - -# Iterate Implementation Plan - -Updates an existing implementation plan based on user feedback. Be skeptical, thorough, and ground changes in codebase reality. - -## Initial Response - -When invoked, parse `$ARGUMENTS` to identify: -- Plan file path (example: `thoughts/shared/plans/2025-10-16-feature.md`) -- Requested changes/feedback - -Handle input scenarios: - -### No plan file provided - -``` -I'll help you iterate on an existing implementation plan. - -Which plan would you like to update? Please provide the path to the plan file (e.g., `thoughts/shared/plans/2025-10-16-feature.md`). - -Tip: You can list recent plans with `ls -lt thoughts/shared/plans/ | head` -``` - -Wait for user input, then re-check for feedback. - -### Plan file provided but no feedback - -``` -I've found the plan at [path]. What changes would you like to make? - -For example: -- "Add a phase for migration handling" -- "Update the success criteria to include performance tests" -- "Adjust the scope to exclude feature X" -- "Split Phase 2 into two separate phases" -``` - -Wait for user input. - -### Plan file and feedback provided - -Proceed immediately to Step 1. No preliminary questions needed. - -## Process Steps - -### Step 1: Read and Understand Current Plan - -1. Read the existing plan file completely. -2. Understand the current structure, phases, and scope. -3. Note the success criteria and implementation approach. -4. Parse the requested changes and identify whether codebase research is required. - -### Step 2: Research if Needed - -Only research if the feedback requires new technical understanding or validation. - -1. Create a research todo list if the work is complex. -2. Use Grep/Glob for quick targeted lookups. -3. Spawn parallel sub-agents via the Task tool for deeper investigation: - - **`codebase-analyzer`** — understand how specific components work - - **`codebase-pattern-finder`** — find existing patterns or conventions to follow - - **`thoughts-analyzer`** — extract insights from prior research in `thoughts/` - - **`thoughts-locator`** — discover relevant documents in `thoughts/` - - **`web-search-researcher`** — research external APIs, libraries, or best practices -4. Wait for all sub-agents to complete before proceeding. -5. Read any new files identified by sub-agents fully into context. - -### Step 3: Present Understanding and Approach - -Before editing the plan, confirm understanding: - -``` -Based on your feedback, I understand you want to: -- [Change 1 with specific detail] -- [Change 2 with specific detail] - -My research found: -- [Relevant code pattern or constraint] -- [Important discovery that affects the change] - -I plan to update the plan by: -1. [Specific modification to make] -2. [Another modification] - -Does this align with your intent? -``` - -Get user confirmation before making changes. - -### Step 4: Update the Plan - -1. Make focused, precise edits to the existing plan. -2. Preserve the existing structure unless explicitly changing it. -3. Keep all file:line references accurate. -4. Update success criteria if needed. -5. Ensure consistency: - - If adding a new phase, follow the existing pattern. - - If modifying scope, update the "What We Are Not Doing" section. - - If changing approach, update "Implementation Approach". - - Maintain automated vs manual success criteria separation. - -### Step 5: Sync and Review - -Present the updates: - -``` -I've updated the plan at `thoughts/shared/plans/[filename].md` - -Changes made: -- [Specific change 1] -- [Specific change 2] - -The updated plan now: -- [Key improvement] -- [Another improvement] - -Would you like any further adjustments? -``` - -Be ready to iterate further based on feedback. - -## Important Guidelines - -### Be Skeptical -- Don't blindly accept change requests that seem problematic. -- Question vague feedback and ask for clarification. -- Verify feasibility with code research. -- Point out conflicts with existing phases. - -### Be Surgical -- Make precise edits, not wholesale rewrites. -- Preserve content that doesn't need changing. -- Research only what the specific changes require. - -### Be Thorough -- Read the entire plan before changing it. -- Research code patterns if changes require new understanding. -- Ensure updated sections maintain quality standards. -- Verify success criteria remain measurable. - -### No Open Questions -- If the requested change raises questions, ask. -- Do not update the plan with unresolved issues. - -## Success Criteria Guidelines - -Always keep two categories: - -1. **Automated Verification**: Commands, tests, compilation, linting -2. **Manual Verification**: UI/UX, performance, edge cases, user acceptance diff --git a/packages/pq-jws/ts/package.json b/packages/pq-jws/ts/package.json index bc38ad8..66589d7 100644 --- a/packages/pq-jws/ts/package.json +++ b/packages/pq-jws/ts/package.json @@ -9,7 +9,7 @@ "dist" ], "scripts": { - "build": "tsc", + "build": "tsc -b", "prepublishOnly": "npm run build" }, "keywords": [ @@ -21,6 +21,9 @@ ], "author": "", "license": "MIT", + "dependencies": { + "pq-oid": "^1.0.1" + }, "devDependencies": { "typescript": "^5.0.0" } diff --git a/packages/pq-jws/ts/src/base64url.ts b/packages/pq-jws/ts/src/base64url.ts new file mode 100644 index 0000000..4281ae5 --- /dev/null +++ b/packages/pq-jws/ts/src/base64url.ts @@ -0,0 +1,9 @@ +import { JwsError } from './errors'; + +export function encodeBase64Url(_value: Uint8Array): string { + throw new JwsError('encodeBase64Url is not implemented yet.'); +} + +export function decodeBase64Url(_value: string): Uint8Array { + throw new JwsError('decodeBase64Url is not implemented yet.'); +} diff --git a/packages/pq-jws/ts/src/compact.ts b/packages/pq-jws/ts/src/compact.ts new file mode 100644 index 0000000..58a7729 --- /dev/null +++ b/packages/pq-jws/ts/src/compact.ts @@ -0,0 +1,6 @@ +import { JwsError } from './errors'; +import type { ParsedCompactJws } from './types'; + +export function parseJwsCompact(_compact: string): ParsedCompactJws { + throw new JwsError('parseJwsCompact is not implemented yet.'); +} diff --git a/packages/pq-jws/ts/src/errors.ts b/packages/pq-jws/ts/src/errors.ts new file mode 100644 index 0000000..e1ae174 --- /dev/null +++ b/packages/pq-jws/ts/src/errors.ts @@ -0,0 +1,20 @@ +export class JwsError extends Error { + constructor(message: string) { + super(message); + this.name = 'JwsError'; + } +} + +export class JwsFormatError extends JwsError { + constructor(message: string) { + super(message); + this.name = 'JwsFormatError'; + } +} + +export class JwsValidationError extends JwsError { + constructor(message: string) { + super(message); + this.name = 'JwsValidationError'; + } +} diff --git a/packages/pq-jws/ts/src/index.ts b/packages/pq-jws/ts/src/index.ts index 2770fbb..f69f606 100644 --- a/packages/pq-jws/ts/src/index.ts +++ b/packages/pq-jws/ts/src/index.ts @@ -1,4 +1,5 @@ -// pq-jws - Post-quantum JSON Web Signature -// Implementation coming soon - -export {}; +export * from './base64url'; +export * from './compact'; +export * from './errors'; +export * from './jws'; +export * from './types'; diff --git a/packages/pq-jws/ts/src/jws.ts b/packages/pq-jws/ts/src/jws.ts new file mode 100644 index 0000000..2dad934 --- /dev/null +++ b/packages/pq-jws/ts/src/jws.ts @@ -0,0 +1,18 @@ +import { JwsError } from './errors'; +import type { JwsVerifier, ParsedCompactJws, SignJwsCompactInput } from './types'; + +export async function signJwsCompact(_input: SignJwsCompactInput): Promise { + throw new JwsError('signJwsCompact is not implemented yet.'); +} + +export async function verifyJwsCompact(_compact: string, _verifier: JwsVerifier): Promise { + throw new JwsError('verifyJwsCompact is not implemented yet.'); +} + +export function decodePayloadText(_parsed: ParsedCompactJws): string { + throw new JwsError('decodePayloadText is not implemented yet.'); +} + +export function decodePayloadJson(_parsed: ParsedCompactJws): T { + throw new JwsError('decodePayloadJson is not implemented yet.'); +} diff --git a/packages/pq-jws/ts/src/types.ts b/packages/pq-jws/ts/src/types.ts new file mode 100644 index 0000000..d3eda73 --- /dev/null +++ b/packages/pq-jws/ts/src/types.ts @@ -0,0 +1,52 @@ +export interface JwsProtectedHeader { + alg: string; + kid?: string; + typ?: string; + cty?: string; + crit?: string[]; + b64?: boolean; + [name: string]: unknown; +} + +export interface CompactJwsSegments { + protectedHeader: string; + payload: string; + signature: string; +} + +export interface ParsedCompactJws { + compact: string; + segments: CompactJwsSegments; + protectedHeader: JwsProtectedHeader; + encodedProtectedHeader: string; + encodedPayload: string; + payload: Uint8Array; + signature: Uint8Array; + signingInput: Uint8Array; +} + +export interface JwsSignerContext { + protectedHeader: JwsProtectedHeader; + payload: Uint8Array; + encodedProtectedHeader: string; + encodedPayload: string; +} + +export interface JwsVerifierContext extends JwsSignerContext {} + +export type JwsSigner = ( + signingInput: Uint8Array, + context: JwsSignerContext, +) => Uint8Array | Promise; + +export type JwsVerifier = ( + signingInput: Uint8Array, + signature: Uint8Array, + context: JwsVerifierContext, +) => boolean | Promise; + +export interface SignJwsCompactInput { + protectedHeader: JwsProtectedHeader; + payload: Uint8Array | string; + signer: JwsSigner; +} diff --git a/packages/pq-jws/ts/tsconfig.json b/packages/pq-jws/ts/tsconfig.json index 0e1d7ae..8c52879 100644 --- a/packages/pq-jws/ts/tsconfig.json +++ b/packages/pq-jws/ts/tsconfig.json @@ -10,5 +10,6 @@ "esModuleInterop": true, "skipLibCheck": true }, - "include": ["src"] + "include": ["src"], + "references": [{ "path": "../../pq-oid/ts" }] }