azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add Sequential Thinking to Code Review + Frontend Validation

Browse Source 
Enhanced code review and frontend validation with intelligent triggers:

Code Review Agent Enhancement:
- Added Sequential Thinking MCP integration for complex issues
- Triggers on 2+ rejections or 3+ critical issues
- New escalation format with root cause analysis
- Comprehensive solution strategies with trade-off evaluation
- Educational feedback to break rejection cycles
- Files: .claude/agents/code-review.md (+308 lines)
- Docs: CODE_REVIEW_ST_ENHANCEMENT.md, CODE_REVIEW_ST_TESTING.md

Frontend Design Skill Enhancement:
- Automatic invocation for ANY UI change
- Comprehensive validation checklist (200+ checkpoints)
- 8 validation categories (visual, interactive, responsive, a11y, etc.)
- 3 validation levels (quick, standard, comprehensive)
- Integration with code review workflow
- Files: .claude/skills/frontend-design/SKILL.md (+120 lines)
- Docs: UI_VALIDATION_CHECKLIST.md (462 lines), AUTOMATIC_VALIDATION_ENHANCEMENT.md (587 lines)

Settings Optimization:
- Repaired .claude/settings.local.json (fixed m365 pattern)
- Reduced permissions from 49 to 33 (33% reduction)
- Removed duplicates, sorted alphabetically
- Created SETTINGS_PERMISSIONS.md documentation

Checkpoint Command Enhancement:
- Dual checkpoint system (git + database)
- Saves session context to API for cross-machine recall
- Includes git metadata in database context
- Files: .claude/commands/checkpoint.md (+139 lines)

Decision Rationale:
- Sequential Thinking MCP breaks rejection cycles by identifying root causes
- Automatic frontend validation catches UI issues before code review
- Dual checkpoints enable complete project memory across machines
- Settings optimization improves maintainability

Total: 1,200+ lines of documentation and enhancements

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-01-17 16:23:52 -07:00
parent 359c2cf1b4
commit 75ce1c2fd5
1089 changed files with 149506 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
.claude/commands/checkpoint.md Normal file
View File

@@ -0,0 +1,179 @@
---
description: Create commit with detailed comment and save session context to database
---
Please create a comprehensive checkpoint that captures BOTH git changes AND session context with the following steps:
## Part 1: Git Checkpoint
1. **Initialize Git if needed**: Run `git init` if git has not been instantiated for the project yet.
2. **Analyze all changes**:
- Run `git status` to see all tracked and untracked files
- Run `git diff` to see detailed changes in tracked files
- Run `git log -5 --oneline` to understand the commit message style of this repository
3. **Stage everything**:
- Add ALL tracked changes (modified and deleted files)
- Add ALL untracked files (new files)
- Use `git add -A` or `git add .` to stage everything
4. **Create a detailed commit message**:
- **First line**: Write a clear, concise summary (50-72 chars) describing the primary change
- Use imperative mood (e.g., "Add feature" not "Added feature")
- Examples: "feat: add user authentication", "fix: resolve database connection issue", "refactor: improve API route structure"
- **Body**: Provide a detailed description including:
- What changes were made (list of key modifications)
- Why these changes were made (purpose/motivation)
- Any important technical details or decisions
- Breaking changes or migration notes if applicable
- **Footer**: Include co-author attribution as shown in the Git Safety Protocol
5. **Execute the commit**: Create the commit with the properly formatted message following this repository's conventions.
## Part 2: Database Context Save
6. **Save session context to database**:
After the commit is complete, save the session context to the ClaudeTools database for cross-machine recall.
**API Endpoint**: `POST http://172.16.3.30:8001/api/conversation-contexts`
**Payload Structure**:
```json
{
"project_id": "<project-uuid>",
"context_type": "checkpoint",
"title": "Checkpoint: <commit-summary>",
"dense_summary": "<comprehensive-session-summary>",
"relevance_score": 8.0,
"tags": ["<extracted-tags>"],
"metadata": {
"git_commit": "<commit-hash>",
"git_branch": "<branch-name>",
"files_changed": ["<file-list>"],
"commit_message": "<full-commit-message>"
}
}
```
**Authentication**: Use JWT token from `.claude/context-recall-config.env`
**How to construct the payload**:
a. **Project ID**: Get from git config or environment
```bash
PROJECT_ID=$(git config --local claude.projectid 2>/dev/null)
```
b. **Title**: Use commit summary line
```
"Checkpoint: feat: Add Sequential Thinking to Code Review Agent"
```
c. **Dense Summary**: Create compressed summary including:
- What was accomplished (from commit message body)
- Key files modified (from git diff --name-only)
- Important decisions or technical details
- Context for future sessions
Example:
```
Enhanced code-review.md with Sequential Thinking MCP integration.
Changes:
- Added trigger conditions for 2+ rejections and 3+ critical issues
- Created enhanced escalation format with root cause analysis
- Added UI_VALIDATION_CHECKLIST.md (462 lines)
- Updated frontend-design skill for automatic invocation
Files: .claude/agents/code-review.md, .claude/skills/frontend-design/SKILL.md,
.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md
Decision: Use Sequential Thinking MCP for complex review issues to break
rejection cycles and provide comprehensive feedback.
Commit: a1b2c3d on branch main
```
d. **Tags**: Extract relevant tags from context (4-8 tags)
```json
["code-review", "sequential-thinking", "frontend-validation", "ui", "documentation"]
```
e. **Metadata**: Include git info for reference
```json
{
"git_commit": "a1b2c3d4e5f",
"git_branch": "main",
"files_changed": [
".claude/agents/code-review.md",
".claude/skills/frontend-design/SKILL.md"
],
"commit_message": "feat: Add Sequential Thinking to Code Review Agent\n\n..."
}
```
**Implementation**:
```bash
# Load config
source .claude/context-recall-config.env
# Get git info
COMMIT_HASH=$(git rev-parse --short HEAD)
BRANCH=$(git rev-parse --abbrev-ref HEAD)
COMMIT_MSG=$(git log -1 --pretty=%B)
FILES=$(git diff --name-only HEAD~1 | tr '\n' ',' | sed 's/,$//')
# Create payload and POST to API
curl -X POST http://172.16.3.30:8001/api/conversation-contexts \
-H "Authorization: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project_id": "'$CLAUDE_PROJECT_ID'",
"context_type": "checkpoint",
"title": "Checkpoint: <commit-summary>",
"dense_summary": "<comprehensive-summary>",
"relevance_score": 8.0,
"tags": ["<tags>"],
"metadata": {
"git_commit": "'$COMMIT_HASH'",
"git_branch": "'$BRANCH'",
"files_changed": ["'$FILES'"],
"commit_message": "'$COMMIT_MSG'"
}
}'
```
7. **Verify both checkpoints**:
- Confirm git commit succeeded (git log -1)
- Confirm database save succeeded (check API response)
- Report both statuses to user
## Benefits of Dual Checkpoint
**Git Checkpoint:**
- Code versioning
- Change history
- Rollback capability
**Database Context:**
- Cross-machine recall
- Semantic search
- Session continuity
- Context for future work
**Together:** Complete project memory across time and machines
## IMPORTANT
- Do NOT skip any files - include everything
- Make the commit message descriptive enough that someone reviewing the git log can understand what was accomplished
- Follow the project's existing commit message conventions (check git log first)
- Include the Claude Code co-author attribution in the commit message
- Ensure database context save includes enough detail for future recall
- Use relevance_score 8.0 for checkpoints (important milestones)
- Extract meaningful tags (4-8 tags) for search/filtering

578
.claude/commands/create-spec.md Normal file
View File

@@ -0,0 +1,578 @@
---
description: Create an app spec for autonomous coding (project)
---
# PROJECT DIRECTORY
This command **requires** the project directory as an argument via `$ARGUMENTS`.
**Example:** `/create-spec generations/my-app`
**Output location:** `$ARGUMENTS/prompts/app_spec.txt` and `$ARGUMENTS/prompts/initializer_prompt.md`
If `$ARGUMENTS` is empty, inform the user they must provide a project path and exit.
---
# GOAL
Help the user create a comprehensive project specification for a long-running autonomous coding process. This specification will be used by AI coding agents to build their application across multiple sessions.
This tool works for projects of any size - from simple utilities to large-scale applications.
---
# YOUR ROLE
You are the **Spec Creation Assistant** - an expert at translating project ideas into detailed technical specifications. Your job is to:
1. Understand what the user wants to build (in their own words)
2. Ask about features and functionality (things anyone can describe)
3. **Derive** the technical details (database, API, architecture) from their requirements
4. Generate the specification files that autonomous coding agents will use
**IMPORTANT: Cater to all skill levels.** Many users are product owners or have functional knowledge but aren't technical. They know WHAT they want to build, not HOW to build it. You should:
- Ask questions anyone can answer (features, user flows, what screens exist)
- **Derive** technical details (database schema, API endpoints, architecture) yourself
- Only ask technical questions if the user wants to be involved in those decisions
**Use conversational questions** to gather information. For questions with clear options, present them as numbered choices that the user can select from. For open-ended exploration, use natural conversation.
---
# CONVERSATION FLOW
There are two paths through this process:
**Quick Path** (recommended for most users): You describe what you want, agent derives the technical details
**Detailed Path**: You want input on technology choices, database design, API structure, etc.
**CRITICAL: This is a CONVERSATION, not a form.**
- Ask questions for ONE phase at a time
- WAIT for the user to respond before moving to the next phase
- Acknowledge their answers before continuing
- Do NOT bundle multiple phases into one message
---
## Phase 1: Project Overview
Start with simple questions anyone can answer:
1. **Project Name**: What should this project be called?
2. **Description**: In your own words, what are you building and what problem does it solve?
3. **Target Audience**: Who will use this?
**IMPORTANT: Ask these questions and WAIT for the user to respond before continuing.**
Do NOT immediately jump to Phase 2. Let the user answer, acknowledge their responses, then proceed.
---
## Phase 2: Involvement Level
Ask the user about their involvement preference:
> "How involved do you want to be in technical decisions?
>
> 1. **Quick Mode (Recommended)** - You describe what you want, I'll handle database, API, and architecture
> 2. **Detailed Mode** - You want input on technology choices and architecture decisions
>
> Which would you prefer?"
**If Quick Mode**: Skip to Phase 3, then go to Phase 4 (Features). You will derive technical details yourself.
**If Detailed Mode**: Go through all phases, asking technical questions.
## Phase 3: Technology Preferences
**For Quick Mode users**, also ask about tech preferences:
> "Any technology preferences, or should I choose sensible defaults?
>
> 1. **Use defaults (Recommended)** - React, Node.js, SQLite - solid choices for most apps
> 2. **I have preferences** - I'll specify my preferred languages/frameworks"
**For Detailed Mode users**, ask specific tech questions about frontend, backend, database, etc.
## Phase 4: Features (THE MAIN PHASE)
This is where you spend most of your time. Ask questions in plain language that anyone can answer.
**Start broad with open conversation:**
> "Walk me through your app. What does a user see when they first open it? What can they do?"
**Then ask about key feature areas:**
> "Let me ask about a few common feature areas:
>
> 1. **User Accounts** - Do users need to log in / have accounts? (Yes with profiles, No anonymous use, or Maybe optional)
> 2. **Mobile Support** - Should this work well on mobile phones? (Yes fully responsive, Desktop only, or Basic mobile)
> 3. **Search** - Do users need to search or filter content? (Yes, No, or Basic only)
> 4. **Sharing** - Any sharing or collaboration features? (Yes, No, or Maybe later)"
**Then drill into the "Yes" answers with open conversation:**
**4a. The Main Experience**
- What's the main thing users do in your app?
- Walk me through a typical user session
**4b. User Accounts** (if they said Yes)
- What can they do with their account?
- Any roles or permissions?
**4c. What Users Create/Manage**
- What "things" do users create, save, or manage?
- Can they edit or delete these things?
- Can they organize them (folders, tags, categories)?
**4d. Settings & Customization**
- What should users be able to customize?
- Light/dark mode? Other display preferences?
**4e. Search & Finding Things** (if they said Yes)
- What do they search for?
- What filters would be helpful?
**4f. Sharing & Collaboration** (if they said Yes)
- What can be shared?
- View-only or collaborative editing?
**4g. Any Dashboards or Analytics?**
- Does the user see any stats, reports, or metrics?
**4h. Domain-Specific Features**
- What else is unique to your app?
- Any features we haven't covered?
**4i. Security & Access Control (if app has authentication)**
Ask about user roles:
> "Who are the different types of users?
>
> 1. **Just regular users** - Everyone has the same permissions
> 2. **Users + Admins** - Regular users and administrators with extra powers
> 3. **Multiple roles** - Several distinct user types (e.g., viewer, editor, manager, admin)"
**If multiple roles, explore in conversation:**
- What can each role see?
- What can each role do?
- Are there pages only certain roles can access?
- What happens if someone tries to access something they shouldn't?
**Also ask about authentication:**
- How do users log in? (email/password, social login, SSO)
- Password requirements? (for security testing)
- Session timeout? Auto-logout after inactivity?
- Any sensitive operations requiring extra confirmation?
**4j. Data Flow & Integration**
- What data do users create vs what's system-generated?
- Are there workflows that span multiple steps or pages?
- What happens to related data when something is deleted?
- Are there any external systems or APIs to integrate with?
- Any import/export functionality?
**4k. Error & Edge Cases**
- What should happen if the network fails mid-action?
- What about duplicate entries (e.g., same email twice)?
- Very long text inputs?
- Empty states (what shows when there's no data)?
**Keep asking follow-up questions until you have a complete picture.** For each feature area, understand:
- What the user sees
- What actions they can take
- What happens as a result
- Who is allowed to do it (permissions)
- What errors could occur
## Phase 4L: Derive Feature Count (DO NOT ASK THE USER)
After gathering all features, **you** (the agent) should tally up the testable features. Do NOT ask the user how many features they want - derive it from what was discussed.
**Typical ranges for reference:**
- **Simple apps** (todo list, calculator, notes): ~20-50 features
- **Medium apps** (blog, task manager with auth): ~100 features
- **Advanced apps** (e-commerce, CRM, full SaaS): ~150-200 features
These are just reference points - your actual count should come from the requirements discussed.
**How to count features:**
For each feature area discussed, estimate the number of discrete, testable behaviors:
- Each CRUD operation = 1 feature (create, read, update, delete)
- Each UI interaction = 1 feature (click, drag, hover effect)
- Each validation/error case = 1 feature
- Each visual requirement = 1 feature (styling, animation, responsive behavior)
**Present your estimate to the user:**
> "Based on what we discussed, here's my feature breakdown:
>
> - [Category 1]: ~X features
> - [Category 2]: ~Y features
> - [Category 3]: ~Z features
> - ...
>
> **Total: ~N features**
>
> Does this seem right, or should I adjust?"
Let the user confirm or adjust. This becomes your `feature_count` for the spec.
## Phase 5: Technical Details (DERIVED OR DISCUSSED)
**For Quick Mode users:**
Tell them: "Based on what you've described, I'll design the database, API, and architecture. Here's a quick summary of what I'm planning..."
Then briefly outline:
- Main data entities you'll create (in plain language: "I'll create tables for users, projects, documents, etc.")
- Overall app structure ("sidebar navigation with main content area")
- Any key technical decisions
Ask: "Does this sound right? Any concerns?"
**For Detailed Mode users:**
Walk through each technical area:
**5a. Database Design**
- What entities/tables are needed?
- Key fields for each?
- Relationships?
**5b. API Design**
- What endpoints are needed?
- How should they be organized?
**5c. UI Layout**
- Overall structure (columns, navigation)
- Key screens/pages
- Design preferences (colors, themes)
**5d. Implementation Phases**
- What order to build things?
- Dependencies?
## Phase 6: Success Criteria
Ask in simple terms:
> "What does 'done' look like for you? When would you consider this app complete and successful?"
Prompt for:
- Must-have functionality
- Quality expectations (polished vs functional)
- Any specific requirements
## Phase 7: Review & Approval
Present everything gathered:
1. **Summary of the app** (in plain language)
2. **Feature count**
3. **Technology choices** (whether specified or derived)
4. **Brief technical plan** (for their awareness)
First ask in conversation if they want to make changes.
**Then ask for final confirmation:**
> "Ready to generate the specification files?
>
> 1. **Yes, generate files** - Create app_spec.txt and update prompt files
> 2. **I have changes** - Let me add or modify something first"
---
# FILE GENERATION
**Note: This section is for YOU (the agent) to execute. Do not burden the user with these technical details.**
## Output Directory
The output directory is: `$ARGUMENTS/prompts/`
Once the user approves, generate these files:
## 1. Generate `app_spec.txt`
**Output path:** `$ARGUMENTS/prompts/app_spec.txt`
Create a new file using this XML structure:
```xml
<project_specification>
<project_name>[Project Name]</project_name>
<overview>
[2-3 sentence description from Phase 1]
</overview>
<technology_stack>
<frontend>
<framework>[Framework]</framework>
<styling>[Styling solution]</styling>
[Additional frontend config]
</frontend>
<backend>
<runtime>[Runtime]</runtime>
<database>[Database]</database>
[Additional backend config]
</backend>
<communication>
<api>[API style]</api>
[Additional communication config]
</communication>
</technology_stack>
<prerequisites>
<environment_setup>
[Setup requirements]
</environment_setup>
</prerequisites>
<feature_count>[derived count from Phase 4L]</feature_count>
<security_and_access_control>
<user_roles>
<role name="[role_name]">
<permissions>
- [Can do X]
- [Can see Y]
- [Cannot access Z]
</permissions>
<protected_routes>
- /admin/* (admin only)
- /settings (authenticated users)
</protected_routes>
</role>
[Repeat for each role]
</user_roles>
<authentication>
<method>[email/password | social | SSO]</method>
<session_timeout>[duration or "none"]</session_timeout>
<password_requirements>[if applicable]</password_requirements>
</authentication>
<sensitive_operations>
- [Delete account requires password confirmation]
- [Financial actions require 2FA]
</sensitive_operations>
</security_and_access_control>
<core_features>
<[category_name]>
- [Feature 1]
- [Feature 2]
- [Feature 3]
</[category_name]>
[Repeat for all feature categories]
</core_features>
<database_schema>
<tables>
<[table_name]>
- [field1], [field2], [field3]
- [additional fields]
</[table_name]>
[Repeat for all tables]
</tables>
</database_schema>
<api_endpoints_summary>
<[category]>
- [VERB] /api/[path]
- [VERB] /api/[path]
</[category]>
[Repeat for all categories]
</api_endpoints_summary>
<ui_layout>
<main_structure>
[Layout description]
</main_structure>
[Additional UI sections as needed]
</ui_layout>
<design_system>
<color_palette>
[Colors]
</color_palette>
<typography>
[Font preferences]
</typography>
</design_system>
<implementation_steps>
<step number="1">
<title>[Phase Title]</title>
<tasks>
- [Task 1]
- [Task 2]
</tasks>
</step>
[Repeat for all phases]
</implementation_steps>
<success_criteria>
<functionality>
[Functionality criteria]
</functionality>
<user_experience>
[UX criteria]
</user_experience>
<technical_quality>
[Technical criteria]
</technical_quality>
<design_polish>
[Design criteria]
</design_polish>
</success_criteria>
</project_specification>
```
## 2. Update `initializer_prompt.md`
**Output path:** `$ARGUMENTS/prompts/initializer_prompt.md`
If the output directory has an existing `initializer_prompt.md`, read it and update the feature count.
If not, copy from `.claude/templates/initializer_prompt.template.md` first, then update.
**CRITICAL: You MUST update the feature count placeholder:**
1. Find the line containing `**[FEATURE_COUNT]**` in the "REQUIRED FEATURE COUNT" section
2. Replace `[FEATURE_COUNT]` with the exact number agreed upon in Phase 4L (e.g., `25`)
3. The result should read like: `You must create exactly **25** features using the...`
**Example edit:**
```
Before: **CRITICAL:** You must create exactly **[FEATURE_COUNT]** features using the `feature_create_bulk` tool.
After: **CRITICAL:** You must create exactly **25** features using the `feature_create_bulk` tool.
```
**Verify the update:** After editing, read the file again to confirm the feature count appears correctly. If `[FEATURE_COUNT]` still appears in the file, the update failed and you must try again.
**Note:** You may also update `coding_prompt.md` if the user requests changes to how the coding agent should work. Include it in the status file if modified.
## 3. Write Status File (REQUIRED - Do This Last)
**Output path:** `$ARGUMENTS/prompts/.spec_status.json`
**CRITICAL:** After you have completed ALL requested file changes, write this status file to signal completion to the UI. This is required for the "Continue to Project" button to appear.
Write this JSON file:
```json
{
"status": "complete",
"version": 1,
"timestamp": "[current ISO 8601 timestamp, e.g., 2025-01-15T14:30:00.000Z]",
"files_written": [
"prompts/app_spec.txt",
"prompts/initializer_prompt.md"
],
"feature_count": [the feature count from Phase 4L]
}
```
**Include ALL files you modified** in the `files_written` array. If the user asked you to also modify `coding_prompt.md`, include it:
```json
{
"status": "complete",
"version": 1,
"timestamp": "2025-01-15T14:30:00.000Z",
"files_written": [
"prompts/app_spec.txt",
"prompts/initializer_prompt.md",
"prompts/coding_prompt.md"
],
"feature_count": 35
}
```
**IMPORTANT:**
- Write this file LAST, after all other files are successfully written
- Only write it when you consider ALL requested work complete
- The UI polls this file to detect completion and show the Continue button
- If the user asks for additional changes after you've written this, you may update it again when the new changes are complete
---
# AFTER FILE GENERATION: NEXT STEPS
Once files are generated, tell the user what to do next:
> "Your specification files have been created in `$ARGUMENTS/prompts/`!
>
> **Files created:**
> - `$ARGUMENTS/prompts/app_spec.txt`
> - `$ARGUMENTS/prompts/initializer_prompt.md`
>
> The **Continue to Project** button should now appear. Click it to start the autonomous coding agent!
>
> **If you don't see the button:** Type `/exit` or click **Exit to Project** in the header.
>
> **Important timing expectations:**
>
> - **First session:** The agent generates features in the database. This takes several minutes.
> - **Subsequent sessions:** Each coding iteration takes 5-15 minutes depending on complexity.
> - **Full app:** Building all [X] features will take many hours across multiple sessions.
>
> **Controls:**
>
> - Press `Ctrl+C` to pause the agent at any time
> - Run `start.bat` (Windows) or `./start.sh` (Mac/Linux) to resume where you left off"
Replace `[X]` with their feature count.
---
# IMPORTANT REMINDERS
- **Meet users where they are**: Not everyone is technical. Ask about what they want, not how to build it.
- **Quick Mode is the default**: Most users should be able to describe their app and let you handle the technical details.
- **Derive, don't interrogate**: For non-technical users, derive database schema, API endpoints, and architecture from their feature descriptions. Don't ask them to specify these.
- **Use plain language**: Instead of "What entities need CRUD operations?", ask "What things can users create, edit, or delete?"
- **Be thorough on features**: This is where to spend time. Keep asking follow-up questions until you have a complete picture.
- **Derive feature count, don't guess**: After gathering requirements, tally up testable features yourself and present the estimate. Don't use fixed tiers or ask users to guess.
- **Validate before generating**: Present a summary including your derived feature count and get explicit approval before creating files.
---
# BEGIN
Start by greeting the user warmly. Ask ONLY the Phase 1 questions:
> "Hi! I'm here to help you create a detailed specification for your app.
>
> Let's start with the basics:
>
> 1. What do you want to call this project?
> 2. In your own words, what are you building?
> 3. Who will use it - just you, or others too?"
**STOP HERE and wait for their response.** Do not ask any other questions yet. Do not use AskUserQuestion yet. Just have a conversation about their project basics first.
After they respond, acknowledge what they said, then move to Phase 2.