Repository navigation
chore: workflow script encapsulation - #24
Conversation
Prevent Claude from shortcutting workflows by hiding implementation details in bash scripts. Claude now runs opaque scripts instead of git/gh commands directly. Scripts added: - list-tasks.sh - find available tasks - start-task.sh - set up branch, assign issue - amend-task.sh - add amendment to task - submit-pr.sh - create/update PR, watch checks - create-task.sh - create GitHub issue - activate-prd.sh - move PRD to active, create milestone - archive-prd.sh - move PRD to archived, close milestone Changes: - task-workflow.md simplified to lifecycle table (no raw commands) - Added permission requirements (user confirmation for key steps) - Removed redundant command files (start-task.md, submit-pr.md) - Updated CLAUDE.md to enforce script usage 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Do not fetch issue details separately - the start-task script provides them as part of starting work. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Claude was trying to create plans before running start-task.sh, but the script provides the issue details needed for planning. Made the sequence explicit: list → propose → confirm → start → plan. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
|
Warning Rate limit exceeded@NTCoding has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 7 minutes and 58 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (7)
📝 WalkthroughWalkthroughAdds a GitHub Issues–based task workflow: new CLI-oriented documentation, seven new shell scripts for task/PRD lifecycle and PR submission, removal of legacy sub-agent docs, and Nx command examples updated in CLAUDE.md. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Shell as Shell Scripts
participant Git
participant GH as GitHubAPI
rect rgb(240,248,255)
User->>Shell: create-task(milestone,title,body)
Shell->>GH: gh issue create
GH-->>Shell: Issue `#N`
Shell-->>User: Issue created (`#N`)
end
rect rgb(245,255,240)
User->>Shell: start-task(`#N`)
Shell->>Git: git checkout main && git pull
Shell->>GH: gh issue view `#N`
GH-->>Shell: issue title/body
Shell->>Git: git checkout -b issue-#N-short-desc
Shell->>GH: gh issue edit `#N` --assignee `@me`
Shell-->>User: branch ready
end
rect rgb(255,250,240)
User->>Shell: amend-task(`#N`, amendment)
Shell->>GH: gh issue view `#N`
Shell->>GH: gh issue edit `#N` (append amendment)
Shell-->>User: amendment saved
end
rect rgb(255,245,245)
User->>Shell: complete-task(`#N`)
Shell->>Shell: run verify gate
Shell->>Shell: run task-check
Shell->>Git: git commit & git push
Shell->>Shell: submit-pr (create/update via gh)
Shell->>GH: gh pr create/update & watch checks
GH-->>Shell: CI results
Shell-->>User: report pass/fail and PR URL
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
Pre-merge checks✅ Passed checks (3 passed)
Comment |
- Add language specifier to fenced code block - Remove trailing spaces - Fix list marker spacing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Deploying living-architecture with
|
| Latest commit: |
b70ba9c
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://e78d49d0.living-architecture.pages.dev |
| Branch Preview URL: | https://workflow-script-encapsulatio.living-architecture.pages.dev |
Ensures markdown formatting errors are caught locally before CI. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🧹 Nitpick comments (8)
scripts/archive-prd.sh (1)
25-26: Validate destination directory exists before moving.If
docs/project/PRD/archived/doesn't exist,git mvwill fail. Whileset -ewill catch this, a more explicit error message would improve the user experience.🔎 Proposed validation before git mv
Add before line 26:
if [[ ! -d "docs/project/PRD/archived" ]]; then echo "Error: Destination directory docs/project/PRD/archived does not exist" >&2 exit 1 fiscripts/start-task.sh (1)
36-37: Validate branch doesn't already exist.If the branch already exists,
git checkout -bwill fail with a generic error. Checking first would provide a clearer error message and better user guidance.🔎 Proposed validation before creating branch
Add before line 37:
if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then echo "Error: Branch $BRANCH_NAME already exists. Delete it first or use a different issue." >&2 exit 1 fiscripts/activate-prd.sh (2)
5-5: Consider adding additional safety flags for bash.The script uses
set -ewhich is good, but consider also adding:
set -uto treat unset variables as errorsset -o pipefailto catch failures in pipelinesThis makes the script more robust against common bash pitfalls.
🔎 Proposed enhancement
-set -e +set -euo pipefail
29-32: Consider making the repository path dynamic.The script hardcodes "NTCoding/living-architecture" in the GitHub API call. While this works for this repository, consider extracting the repository path dynamically to improve reusability:
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)🔎 Optional enhancement for reusability
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner) + # Create the milestone -gh api repos/NTCoding/living-architecture/milestones \ +gh api "repos/${REPO}/milestones" \ --method POST \ --field title="$PRD_NAME" \ - --field description="See https://github.com/NTCoding/living-architecture/blob/main/${DEST}" + --field description="See https://github.com/${REPO}/blob/main/${DEST}"scripts/list-tasks.sh (3)
5-5: Consider adding additional safety flags for bash.Like
activate-prd.sh, this script would benefit from additional safety flags:
set -uto treat unset variables as errorsset -o pipefailto catch failures in pipelines🔎 Proposed enhancement
-set -e +set -euo pipefail
30-34: Consider handling multiple active PRDs explicitly.The script uses
head -1to select the first active PRD file, but silently ignores additional PRDs if they exist. Consider explicitly checking for this scenario and either:
- Requiring exactly one active PRD (error if multiple found)
- Documenting that it uses the first alphabetically
This prevents confusion when multiple PRDs are accidentally left active.
🔎 Optional enhancement
PRD_FILE=$(ls "$PRD_DIR"/*.md 2>/dev/null | head -1) if [[ -z "$PRD_FILE" ]]; then echo "Error: No active PRD found in $PRD_DIR" >&2 exit 1 fi + +PRD_COUNT=$(ls "$PRD_DIR"/*.md 2>/dev/null | wc -l) +if [[ "$PRD_COUNT" -gt 1 ]]; then + echo "Warning: Multiple active PRDs found. Using: $(basename "$PRD_FILE")" >&2 +fi
45-55: LGTM! GitHub CLI usage is well-structured.Good practices:
- Array for building command arguments safely
- Conditional argument addition
- Proper array expansion
- Clean jq formatting for output
Optional: The script fetches labels in the JSON but doesn't display them. Consider showing labels if they exist to provide more context:
gh "${GH_ARGS[@]}" --json number,title,labels --jq '.[] | "#\(.number): \(.title) [\(.labels | map(.name) | join(", "))]"'docs/workflow/task-workflow.md (1)
11-20: Clarify the distinction between command notations (slash vs. script paths).The Lifecycle Steps table mixes two command notations:
/create-tasksand/complete-taskuse slash notation, while other steps use./scripts/script-name.shpaths. The PR introduces both.claude/commands/andscripts/directories per the summary, suggesting these are intentionally different (Claude commands vs. shell scripts). However, users may not understand when to use each type.Consider adding a brief note explaining the notation difference, or consolidate the reference style for consistency.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (13)
.claude/commands/complete-task.md.claude/commands/create-tasks.md.claude/commands/start-task.md.claude/commands/submit-pr.mdCLAUDE.mddocs/workflow/task-workflow.mdscripts/activate-prd.shscripts/amend-task.shscripts/archive-prd.shscripts/create-task.shscripts/list-tasks.shscripts/start-task.shscripts/submit-pr.sh
💤 Files with no reviewable changes (2)
- .claude/commands/submit-pr.md
- .claude/commands/start-task.md
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx,js,jsx,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Use domain terminology from
docs/architecture/domain-terminology/contextive/definitions.glossary.yml- do not invent new terms or use technical jargon when domain terminology exists
Files:
docs/workflow/task-workflow.mdCLAUDE.md
**/*.{ts,tsx,js,jsx,json,md}
📄 CodeRabbit inference engine (CLAUDE.md)
All code must follow
docs/conventions/codebase-structure.md
Files:
docs/workflow/task-workflow.mdCLAUDE.md
🧠 Learnings (27)
📓 Common learnings
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Follow the exact workflow steps documented in `docs/workflow/task-workflow.md` before finding/starting a task, running gh commands, creating commits or PRs, or updating requirements
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/workflow/code-review.md:0-0
Timestamp: 2026-01-03T11:38:30.208Z
Learning: After addressing issues from code review, complete the task by following @/docs/workflow/task-workflow.md → Completing Tasks
📚 Learning: 2026-01-03T11:38:30.208Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/workflow/code-review.md:0-0
Timestamp: 2026-01-03T11:38:30.208Z
Learning: After addressing issues from code review, complete the task by following @/docs/workflow/task-workflow.md → Completing Tasks
Applied to files:
.claude/commands/complete-task.mddocs/workflow/task-workflow.md.claude/commands/create-tasks.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Follow the exact workflow steps documented in `docs/workflow/task-workflow.md` before finding/starting a task, running gh commands, creating commits or PRs, or updating requirements
Applied to files:
.claude/commands/complete-task.mddocs/workflow/task-workflow.md.claude/commands/create-tasks.mdCLAUDE.md
📚 Learning: 2026-01-02T11:58:27.001Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-cli/CLAUDE.md:0-0
Timestamp: 2026-01-02T11:58:27.001Z
Learning: When modifying CLI commands in the riviere-cli tool, update the corresponding workflow prompts in docs/workflow/ directory (step-1 through step-6) to keep the extraction workflow in sync
Applied to files:
docs/workflow/task-workflow.md
📚 Learning: 2026-01-02T11:58:27.001Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-cli/CLAUDE.md:0-0
Timestamp: 2026-01-02T11:58:27.001Z
Learning: After modifying CLI commands, run `nx generate-docs riviere-cli` to regenerate CLI reference documentation
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Always use nx commands for build, test, lint operations. Do not run npm/pnpm directly (e.g., use `pnpm nx build [project-name]` instead of `pnpm build`)
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/tsconfig*.json : Run `pnpm nx sync` after modifying tsconfig references or adding dependencies between projects
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T11:38:30.207Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/workflow/code-review.md:0-0
Timestamp: 2026-01-03T11:38:30.207Z
Learning: Applies to docs/workflow/**/*.{js,jsx,ts,tsx,!**/*.test.*,!**/*.spec.*} : Check all production code files comply with software design conventions in @/docs/conventions/software-design.md and standard patterns in @/docs/conventions/standard-patterns.md
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T17:37:55.698Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/conventions/codebase-structure.md:0-0
Timestamp: 2026-01-03T17:37:55.698Z
Learning: Monorepo structure: apps/ contains deployable applications, packages/ contains shared libraries published to npm
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T17:37:55.698Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/conventions/codebase-structure.md:0-0
Timestamp: 2026-01-03T17:37:55.698Z
Learning: Create packages only when code is used by 2+ apps, represents a distinct domain concept, or needs npm publication
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T17:37:55.698Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/conventions/codebase-structure.md:0-0
Timestamp: 2026-01-03T17:37:55.698Z
Learning: Applies to docs/conventions/**/tsconfig*.json : Each app/package must have a 3-file tsconfig structure: tsconfig.json (editor entry point), tsconfig.lib.json (production), and tsconfig.spec.json (tests)
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/*.{ts,tsx,js,jsx,json,md} : All code must follow `docs/conventions/codebase-structure.md`
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T17:37:55.698Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/conventions/codebase-structure.md:0-0
Timestamp: 2026-01-03T17:37:55.698Z
Learning: Applies to docs/conventions/**/*.{ts,tsx,js,mjs} : Import from package names using living-architecture/[pkg-name] instead of relative paths like ../../packages/[pkg-name]
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T17:37:55.698Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/conventions/codebase-structure.md:0-0
Timestamp: 2026-01-03T17:37:55.698Z
Learning: Applies to docs/conventions/**/package.json : When importing from another project, add workspace dependency explicitly in package.json as "living-architecture/[pkg-name]": "workspace:*"
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/package.json : Add `living-architecture/[pkg-name]: workspace:*` to dependencies when importing from another project
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Use cross-project imports with package names (e.g., `import { X } from 'living-architecture/[pkg-name]'`), not relative paths
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Use NX generators to create projects - don't manually create project folders. Use `pnpm nx g nx/js:library` or `pnpm nx g nx/node:application`
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T11:38:30.207Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/workflow/code-review.md:0-0
Timestamp: 2026-01-03T11:38:30.207Z
Learning: Applies to docs/workflow/**/*.{js,jsx,ts,tsx,!**/*.test.*,!**/*.spec.*} : Verify all production code files align with architecture boundaries and layering requirements as defined in @/docs/architecture/overview.md and @/docs/conventions/codebase-structure.md
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/*.{test,spec}.{ts,tsx} : Follow `docs/conventions/testing.md` for all test implementations
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T17:37:55.698Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/conventions/codebase-structure.md:0-0
Timestamp: 2026-01-03T17:37:55.698Z
Learning: Run nx sync after adding dependencies or creating new projects
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Follow `docs/conventions/software-design.md` when writing, editing, refactoring, or reviewing code
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T11:38:30.207Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/workflow/code-review.md:0-0
Timestamp: 2026-01-03T11:38:30.207Z
Learning: Applies to docs/workflow/**/*.{js,jsx,ts,tsx,!**/*.test.*,!**/*.spec.*} : Check production code against anti-patterns defined in @/docs/conventions/anti-patterns.md - hard failure unless documented exception exists
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-02T11:58:34.018Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-02T11:58:34.018Z
Learning: Read and follow all instructions in CLAUDE.md
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Avoid patterns documented in `docs/conventions/anti-patterns.md`
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T17:37:22.708Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/conventions/software-design.md:0-0
Timestamp: 2026-01-03T17:37:22.708Z
Learning: Applies to docs/conventions/**/*.{ts,tsx} : No code comments. Comments are a failure to express intent in code. If you need a comment to explain what code does, the code isn't clear enough—refactor it.
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T17:37:55.698Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/conventions/codebase-structure.md:0-0
Timestamp: 2026-01-03T17:37:55.698Z
Learning: Use NX generators to add projects instead of creating folders manually
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-03T23:57:20.921Z
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-03T23:57:20.921Z
Learning: Applies to **/*.{ts,tsx,js,jsx,md} : Use domain terminology from `docs/architecture/domain-terminology/contextive/definitions.glossary.yml` - do not invent new terms or use technical jargon when domain terminology exists
Applied to files:
CLAUDE.md
🪛 GitHub Actions: CI
CLAUDE.md
[error] 9-9: MD040/fenced-code-language Fenced code blocks should have a language specified
[error] 106-106: MD009/no-trailing-spaces Trailing spaces
[error] 108-108: MD009/no-trailing-spaces Trailing spaces
[error] 110-110: MD030/list-marker-space Spaces after list markers
🪛 LanguageTool
docs/workflow/task-workflow.md
[grammar] ~38-~38: Ensure spelling is correct
Context: .... Activate PRD — Moving a PRD from notstarted to active. Archive PRD — All tasks...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
CLAUDE.md
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Cloudflare Pages
🔇 Additional comments (12)
scripts/create-task.sh (1)
1-23: LGTM!The script correctly validates required arguments, uses proper quoting throughout, and handles errors with
set -e. The usage message is clear and goes to stderr as expected.scripts/submit-pr.sh (1)
44-50: Excellent precondition checks and CI integration.The uncommitted changes validation ensures a clean working tree before PR operations, and the CI watching with status reporting provides clear feedback on check results. The error messages guide users on next steps appropriately.
Also applies to: 75-106
scripts/amend-task.sh (1)
1-32: LGTM!The script properly validates arguments, uses correct quoting, and builds the amended body with appropriate Markdown formatting. The
ghCLI will provide clear error messages if the issue doesn't exist.scripts/start-task.sh (1)
14-26: Solid workflow automation with good user feedback.The script correctly ensures a clean starting state by switching to main and pulling latest changes. The issue assignment and detailed output provide clear context for beginning work.
Also applies to: 39-51
CLAUDE.md (2)
96-96: LGTM! Strengthened workflow guidance improves compliance.The emphasized directive to follow the task workflow exactly aligns with the PR's objective to improve workflow adherence and reduce non-compliance.
44-56: LGTM! Command simplification is correct.The update from
pnpm nxto plainnximproves clarity and aligns with the PR's objective to simplify command usage.However, note that
.claude/commands/complete-task.mdline 13 still usespnpm nx run-many -t lint,typecheck,test, which is inconsistent with this updated pattern. Please ensure all documentation uses the same command format.⛔ Skipped due to learnings
Learnt from: CR Repo: NTCoding/living-architecture PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-01-03T23:57:20.921Z Learning: Applies to **/*.{ts,tsx,js,jsx} : Always use nx commands for build, test, lint operations. Do not run npm/pnpm directly (e.g., use `pnpm nx build [project-name]` instead of `pnpm build`)Learnt from: CR Repo: NTCoding/living-architecture PR: 0 File: docs/conventions/codebase-structure.md:0-0 Timestamp: 2026-01-03T17:37:55.698Z Learning: Run nx sync after adding dependencies or creating new projectsLearnt from: CR Repo: NTCoding/living-architecture PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-01-03T23:57:20.921Z Learning: Applies to **/tsconfig*.json : Run `pnpm nx sync` after modifying tsconfig references or adding dependencies between projectsLearnt from: CR Repo: NTCoding/living-architecture PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-01-03T23:57:20.921Z Learning: Use NX generators to create projects - don't manually create project folders. Use `pnpm nx g nx/js:library` or `pnpm nx g nx/node:application`Learnt from: CR Repo: NTCoding/living-architecture PR: 0 File: docs/conventions/codebase-structure.md:0-0 Timestamp: 2026-01-03T17:37:55.698Z Learning: Use NX generators to add projects instead of creating folders manuallyscripts/activate-prd.sh (1)
13-21: LGTM! Path handling and validation are robust.Good practices observed:
- All variable references properly quoted
- File existence validated before operations
- Clear error messages with stderr redirect
.claude/commands/create-tasks.md (1)
7-12: LGTM! Task breakdown criteria follow best practices.The criteria enforce:
- Small batch sizes (1 day max)
- INVEST principles for well-formed stories
- SPIDR splitting techniques for managing complexity
This guidance will help maintain a healthy task backlog.
scripts/list-tasks.sh (1)
36-43: LGTM! Milestone extraction logic is correct.The parameter expansion technique correctly extracts the milestone name from the PRD filename format.
.claude/commands/complete-task.md (2)
15-15: Script interface verified.The
./scripts/submit-pr.shscript exists and correctly accepts the--titleand--bodyflags as documented. The implementation matches the usage pattern shown in line 15.
13-13: Fix command inconsistencies with CLAUDE.md.The verify gate command has two inconsistencies with the updated CLAUDE.md:
- Uses
pnpm nx run-manyinstead of plainnx run-many- Missing
--coverageflag that CLAUDE.md line 67 includes for verification🔎 Proposed fix
-1. Run verify gate: `pnpm nx run-many -t lint,typecheck,test` +1. Run verify gate: `nx run-many -t lint,typecheck,test --coverage`⛔ Skipped due to learnings
Learnt from: CR Repo: NTCoding/living-architecture PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-01-03T23:57:20.921Z Learning: Applies to **/*.{ts,tsx,js,jsx} : Always use nx commands for build, test, lint operations. Do not run npm/pnpm directly (e.g., use `pnpm nx build [project-name]` instead of `pnpm build`)Learnt from: CR Repo: NTCoding/living-architecture PR: 0 File: docs/workflow/code-review.md:0-0 Timestamp: 2026-01-03T11:38:30.207Z Learning: Applies to docs/workflow/**/*.{test,spec}.{js,jsx,ts,tsx} : Review usage of `/* v8 ignore next -- preserve */` in test files - only allow when code is unreachable and required for compiler satisfaction; otherwise suggest extracting code or writing tests to mock behaviorLearnt from: CR Repo: NTCoding/living-architecture PR: 0 File: docs/workflow/code-review.md:0-0 Timestamp: 2026-01-03T11:38:30.207Z Learning: Applies to docs/workflow/**/*.{js,jsx,ts,tsx,!**/*.test.*,!**/*.spec.*} : Verify all production code files align with architecture boundaries and layering requirements as defined in @/docs/architecture/overview.md and @/docs/conventions/codebase-structure.mdLearnt from: CR Repo: NTCoding/living-architecture PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-01-03T23:57:20.921Z Learning: Applies to **/tsconfig*.json : Run `pnpm nx sync` after modifying tsconfig references or adding dependencies between projectsLearnt from: CR Repo: NTCoding/living-architecture PR: 0 File: docs/workflow/code-review.md:0-0 Timestamp: 2026-01-03T11:38:30.207Z Learning: Applies to docs/workflow/**/*.{js,jsx,ts,tsx,!**/*.test.*,!**/*.spec.*} : Check all production code files comply with software design conventions in @/docs/conventions/software-design.md and standard patterns in @/docs/conventions/standard-patterns.mdLearnt from: CR Repo: NTCoding/living-architecture PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-01-03T23:57:20.921Z Learning: Use NX generators to create projects - don't manually create project folders. Use `pnpm nx g nx/js:library` or `pnpm nx g nx/node:application`docs/workflow/task-workflow.md (1)
1-40: Excellent restructuring for clarity and enforcement.The conversion from narrative guidance to a step-based table format significantly improves usability and aligns well with the PR objectives. The explicit mandatory instruction (line 3), clear permission levels, and sequencing guidance (especially the warning in line 30 not to plan before running start-task) effectively enforce the workflow and prevent common mistakes.
The "When to Use Each Step" section provides excellent context—particularly the clarification that
start-taskmust run first to provide issue details needed for planning, which directly addresses workflow compliance.
| When writing, editing, refactoring, or reviewing code: | ||
|
|
||
| - always follow `docs/conventions/software-design.md` | ||
| - always follow `docs/conventions/software-design.md` | ||
| - look for standard implementation patterns defined in `docs/conventions/standard-patterns.md` | ||
| - avoid `@docs/conventions/anti-patterns.md` | ||
| - avoid `@docs/conventions/anti-patterns.md` | ||
|
|
There was a problem hiding this comment.
Fix pipeline failures: Remove trailing spaces and fix list marker spacing.
Multiple markdown formatting issues are blocking the pipeline:
- Line 106: Trailing spaces
- Line 108: Trailing spaces
- Line 110: Incorrect list marker spacing (double space after dash)
🔎 Proposed fix
-When writing, editing, refactoring, or reviewing code:
+When writing, editing, refactoring, or reviewing code:
-- always follow `docs/conventions/software-design.md`
+- always follow `docs/conventions/software-design.md`
- look for standard implementation patterns defined in `docs/conventions/standard-patterns.md`
-- avoid `@docs/conventions/anti-patterns.md`
+- avoid `@docs/conventions/anti-patterns.md`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| When writing, editing, refactoring, or reviewing code: | |
| - always follow `docs/conventions/software-design.md` | |
| - always follow `docs/conventions/software-design.md` | |
| - look for standard implementation patterns defined in `docs/conventions/standard-patterns.md` | |
| - avoid `@docs/conventions/anti-patterns.md` | |
| - avoid `@docs/conventions/anti-patterns.md` | |
| When writing, editing, refactoring, or reviewing code: | |
| - always follow `docs/conventions/software-design.md` | |
| - look for standard implementation patterns defined in `docs/conventions/standard-patterns.md` | |
| - avoid `@docs/conventions/anti-patterns.md` | |
🧰 Tools
🪛 GitHub Actions: CI
[error] 106-106: MD009/no-trailing-spaces Trailing spaces
[error] 108-108: MD009/no-trailing-spaces Trailing spaces
[error] 110-110: MD030/list-marker-space Spaces after list markers
🤖 Prompt for AI Agents
In CLAUDE.md around lines 106 to 111, there are Markdown formatting issues:
remove trailing spaces on lines 106 and 108, and fix the list marker spacing on
line 110 by ensuring a single space after the dash (e.g. "- look for ..."
instead of "- look for ..."); adjust any other list items in this block to use
consistent single-space after the dash and save the file to eliminate trailing
whitespace so the pipeline passes.
| --label) | ||
| LABEL_FILTER="$2" | ||
| shift 2 | ||
| ;; |
There was a problem hiding this comment.
Add validation for --label argument value.
The script doesn't validate that $2 exists when --label is provided. If someone runs ./scripts/list-tasks.sh --label without a value, the script could fail unexpectedly or consume an unintended argument.
🔎 Proposed fix
--label)
+ if [[ -z "${2:-}" ]]; then
+ echo "Error: --label requires a value" >&2
+ echo "Usage: ./scripts/list-tasks.sh [--label <label>]" >&2
+ exit 1
+ fi
LABEL_FILTER="$2"
shift 2
;;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --label) | |
| LABEL_FILTER="$2" | |
| shift 2 | |
| ;; | |
| --label) | |
| if [[ -z "${2:-}" ]]; then | |
| echo "Error: --label requires a value" >&2 | |
| echo "Usage: ./scripts/list-tasks.sh [--label <label>]" >&2 | |
| exit 1 | |
| fi | |
| LABEL_FILTER="$2" | |
| shift 2 | |
| ;; |
🤖 Prompt for AI Agents
In scripts/list-tasks.sh around lines 11 to 14, the --label case assigns
LABEL_FILTER="$2" without validating that a value was provided; add a check
after detecting --label to ensure "$2" is non-empty and does not start with '-'
(indicating another option); if the value is missing, print a clear usage/error
message to stderr and exit with a non-zero status; otherwise assign
LABEL_FILTER="$2" and shift 2 as before.
Aligns command example with explanation using consistent <milestone> and <deliverable> placeholder names. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Use dynamic repo lookup instead of hard-coded path - Remove dangerous git add -A (git mv already stages) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Fix "notstarted" → "not started" in task-workflow.md - Add --label argument validation in list-tasks.sh - Add empty branch name fallback in start-task.sh - Add main branch protection in submit-pr.sh 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
|
1 participant
Add better guidelines and signposts and deterministic steps for task management workflow to improve compliance
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.