From f631cc819a6220ca4a6d22d83ebdd8fdc8a405df Mon Sep 17 00:00:00 2001 From: Nathan Huh Date: Thu, 26 Mar 2026 11:33:39 +0900 Subject: [PATCH] chore: add CLAUDE.md, update PLAN.md, and commit .claude skills - Create CLAUDE.md with issue-first workflow rule and code patterns - Add M3.6.1 (Route53 phase 1) as complete in PLAN.md - Add M3.9 (IAM Users) to PLAN.md per #14 - Update implementation order to include M3.9 - Commit .claude/commands/ skills: implement-feature, ship-pr, create-issues, update-docs, update-issues --- .claude/commands/create-issues.md | 26 +++++++++++++ .claude/commands/implement-feature.md | 54 +++++++++++++++++++++++++++ .claude/commands/ship-pr.md | 21 +++++++++++ .claude/commands/update-docs.md | 18 +++++++++ .claude/commands/update-issues.md | 30 +++++++++++++++ CLAUDE.md | 16 ++++++++ PLAN.md | 12 +++++- 7 files changed, 175 insertions(+), 2 deletions(-) create mode 100644 .claude/commands/create-issues.md create mode 100644 .claude/commands/implement-feature.md create mode 100644 .claude/commands/ship-pr.md create mode 100644 .claude/commands/update-docs.md create mode 100644 .claude/commands/update-issues.md create mode 100644 CLAUDE.md diff --git a/.claude/commands/create-issues.md b/.claude/commands/create-issues.md new file mode 100644 index 0000000..07f9c14 --- /dev/null +++ b/.claude/commands/create-issues.md @@ -0,0 +1,26 @@ +Create GitHub issues for planned but unimplemented features. + +## Input +$ARGUMENTS — optional scope (e.g., "M3 services" or "all remaining") + +## Workflow + +1. Read `PLAN.md` to identify planned milestones and features. +2. Run `gh issue list --state all --limit 50` to see existing issues. +3. Identify features in PLAN.md that don't have corresponding issues yet. +4. For each missing feature, create an issue with `gh issue create`: + - Title: `feat: (M.)` with the milestone reference + - Label: `enhancement` + - Body format: + ``` + ## Summary + <1-2 sentence description> + + ## Details + + + ## Checklist + + ``` +5. Skip features that already have open or closed issues. +6. Report the list of created issues with URLs. diff --git a/.claude/commands/implement-feature.md b/.claude/commands/implement-feature.md new file mode 100644 index 0000000..00a9d8f --- /dev/null +++ b/.claude/commands/implement-feature.md @@ -0,0 +1,54 @@ +Implement a feature for the unic TUI tool. + +## Input +$ARGUMENTS — feature description or GitHub issue number (e.g., "CloudWatch Logs browser" or "#29") + +## Phase 1: Gather Context + +1. If the argument is a GitHub issue number, fetch it with `gh issue view `. Read the full body, checklist, and comments. +2. If the argument is a description, search for a matching issue with `gh issue list --search ""` and read it if found. +3. Read `PLAN.md` to find the relevant milestone and any design decisions. +4. Read `.kiro/docs/architecture-en.md` if it exists for architectural context. +5. Explore the codebase to understand existing patterns: + - `internal/domain/model.go` and `catalog.go` for service/feature registration + - `internal/services/aws/repository.go` for client interfaces + - Pick one completed service (e.g., `rds.go`, `rds_model.go`, `rds_test.go`) as the reference implementation + - `internal/app/app.go` for screen enum, Update handlers, View functions + +## Phase 2: Interview + +Ask the user to clarify before implementing. Tailor questions based on what the issue and docs leave ambiguous: + +- What AWS API operations are needed? (list, describe, create, delete, etc.) +- What data should be shown in the list view vs detail view? +- Are there any actions (mutating operations) needed? If so, which need confirmation? +- Any edge cases or constraints specific to their AWS environment? +- Should this go on a separate branch, or add to an existing one? + +Skip questions that are already answered by the GitHub issue or PLAN.md. + +## Phase 3: Plan + +Enter plan mode. Design the implementation following existing patterns: +- Domain constants and catalog registration +- AWS client interface, implementation, and model +- TUI screens with scroll windowing (`visibleLines := max(m.height-N, 5)`) +- Tests using mock clients +- Destructive actions must use type-to-confirm (see `updateRDSConfirm` pattern) + +## Phase 4: Implement + +After plan approval, implement in this order: +1. Domain model (`internal/domain/model.go`, `catalog.go`) +2. AWS service layer (`internal/services/aws/.go`, `_model.go`) +3. Client interface update (`internal/services/aws/repository.go`) +4. TUI integration (`internal/app/app.go`) +5. Tests (`internal/services/aws/_test.go`, `internal/app/app_test.go`) + +## Phase 5: Verify + +1. `make test` — all tests pass +2. `make build` — binary compiles +3. Report what was implemented and suggest running `/ship-pr` to create the PR + +Do NOT add Co-Authored-By lines to commits. diff --git a/.claude/commands/ship-pr.md b/.claude/commands/ship-pr.md new file mode 100644 index 0000000..6da8202 --- /dev/null +++ b/.claude/commands/ship-pr.md @@ -0,0 +1,21 @@ +Stage, commit, push, and create a PR for the current changes. + +## Input +$ARGUMENTS — optional branch name and PR title hint + +## Workflow + +1. Run `make test` to verify all tests pass. Stop if tests fail. +2. Run `make build` to verify compilation. Stop if build fails. +3. Check `git status` and `git diff --stat` to understand what changed. +4. Create a feature branch from main using `feat/` prefix (e.g., `feat/rds-aurora-support`). Use the argument as a hint for the branch name, or infer from the changes. +5. Stage only the relevant modified files by name. Never use `git add -A` or `git add .`. +6. Commit with a conventional commit message (`feat:`, `fix:`, `docs:`, etc.) following the style in `git log --oneline -10`. Include a body with bullet points summarizing key changes. Do NOT add Co-Authored-By lines. +7. Push with `-u origin `. +8. Create a PR using `gh pr create` following the template in `.github/pull_request_template.md`: + - Summary: what changed and why + - Related Issues: reference any GitHub issues if applicable + - Validation: describe how it was tested + - Checklist: scope, docs, tests, breaking changes + +Return the PR URL when done. diff --git a/.claude/commands/update-docs.md b/.claude/commands/update-docs.md new file mode 100644 index 0000000..943c077 --- /dev/null +++ b/.claude/commands/update-docs.md @@ -0,0 +1,18 @@ +Update project documentation to reflect current state of the codebase. + +## Input +$ARGUMENTS — optional description of what changed (e.g., "RDS is now complete") + +## Workflow + +1. Read `README.md`, `PLAN.md`, and check recent `git log --oneline -10` to understand what shipped. +2. Update `README.md`: + - Feature matrix: change status emojis (🚧 → ✅) for completed features + - Key bindings table: add any new bindings + - Configuration: update if new config options were added +3. Update `PLAN.md`: + - Mark completed milestones with ✅ + - Update implementation order notes at the bottom + - Add new sub-items to milestones if features were expanded +4. Commit with `docs:` prefix. Do NOT add Co-Authored-By lines. +5. Push to the current branch. diff --git a/.claude/commands/update-issues.md b/.claude/commands/update-issues.md new file mode 100644 index 0000000..68b9aed --- /dev/null +++ b/.claude/commands/update-issues.md @@ -0,0 +1,30 @@ +Review open GitHub issues against the current state of the repo and suggest updates. + +## Input +$ARGUMENTS — optional scope filter (e.g., "Route53", "M3", or issue number like "#13") + +## Workflow + +1. Fetch open issues: `gh issue list --state open --limit 50`. +2. Read `PLAN.md` and check recent git history (`git log --oneline -20`) to understand current repo state. +3. For each open issue (or filtered subset), assess: + - **Already done?** — Check if the feature/fix has been merged (search PRs, git log, code). + - **Partially done?** — Check if some checklist items are complete and the issue body needs updating. + - **Stale or superseded?** — Check if the issue is no longer relevant given current code or plan changes. + - **Missing details?** — Check if the issue body is missing context that now exists (e.g., related PRs, design decisions). + - **Labels/milestone wrong?** — Check if labels or references need updating. +4. Present findings to the user as a numbered list: + ``` + 1. #13 — "feat: Add Route53 ListHostedZones support" + → Implemented in PR #38. Suggest: close issue. + 2. #40 — "feat: Route53 record mutations (M3.6 phase 2)" + → Still open, no work started. No changes needed. + ``` +5. Ask the user which actions to take (close, edit body, add comment, update labels, no change). +6. Execute only the approved actions using `gh issue close`, `gh issue edit`, or `gh issue comment`. +7. Report what was updated. + +## Rules +- Never close or edit an issue without user confirmation. +- When editing issue bodies, show the diff of what will change before applying. +- If an issue references a PR, check if the PR is merged. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..da24d5e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,16 @@ +# unic — Claude Code Guidelines + +## Workflow + +- **Never commit directly.** Always follow this order: + 1. Create a GitHub issue first + 2. Work on the implementation + 3. Push to a feature branch and create a PR referencing the issue +- This applies to all changes — features, fixes, improvements, docs. + +## Code Patterns + +- Follow existing patterns in the codebase (see RDS implementation as reference) +- Use lipgloss for styled TUI output — column-aligned tables with dimmed labels +- Tests use mock client interfaces (see `rds_test.go` pattern) +- Scroll windowing: `visibleLines := max(m.height-N, 5)` diff --git a/PLAN.md b/PLAN.md index f68726f..dbf9965 100644 --- a/PLAN.md +++ b/PLAN.md @@ -141,6 +141,14 @@ unic/ - Create / Delete records - Show change status (PENDING → INSYNC) +**M3.6.1 — Route 53 (Phase 1)** ✅ +- List hosted zones → drill into DNS records → record detail view +- Filter support on zone list and record list + +**M3.9 — IAM Users** +- List IAM users with metadata (creation date, last activity, MFA status) +- View user details (attached policies, groups, access keys) + **M3.7 — CloudWatch Logs** - List log groups → log streams - Live tail (polling via `FilterLogEvents`) @@ -241,7 +249,7 @@ Prerequisite: `go get github.com/sahilm/fuzzy` ``` M1.1 → M1.2 → M2.1 → M2.2 → M2.3 → M2.4 ↓ - M3.1 ~ M3.8 (independent, any order) + M3.1 ~ M3.9 (independent, any order) ↓ M4.1 → M4.2 → M4.3 ↓ @@ -255,7 +263,7 @@ Note: M5.2 (textinput) provides the foundation for M6 (enhanced search) — they - M1 is complete; M2 is deferred (relying on AWS SDK default credential chain) - M2.1 (Context-based auth with SSO, credential, assume-role) is complete - M3 services are independent of each other, build in any order -- M3.1 (VPC), M3.2 (RDS), and M3.4 (SSM Sessions) are complete +- M3.1 (VPC), M3.2 (RDS), M3.4 (SSM Sessions), and M3.6.1 (Route53 phase 1) are complete - M4.3 (Distribution) is partially done (GoReleaser + GitHub Actions) - M5 and M6 can begin independently of remaining M3/M4 work