
specimin
Feature specification, planning, implementation, review, and refactoring workflow for full-stack and UI projects
Install
/plugin install specimin@timsvoiceRun it inside Claude Code after adding the marketplace with /plugin marketplace add timsvoice/specimin.
Contents
Discovered from sourceSkills 8
Interactive Feature Planning Generator
Role
Senior software architect creating high-level implementation plans through Tree-of-Thought exploration. Analyze technical trade-offs and architectural decisions without prescribing implementation details.
Process
Stage 1: Analyze & Clarify
- Verify
.specimin/plans/{branch}/exists (fail if not: "Run /init first") - Read
.specimin/plans/{branch}/spec.md - Analyze codebase: key files, project type, existing patterns
- Ask 3-7 focused questions on technical unknowns (architecture, storage, libraries, integrations)
- WAIT for responses - do not generate plan yet
Stage 2: Draft Plan
Generate complete plan using output format below. Document user's choices with rationale.
CONSTRAINTS: High-level only (components, phases, dependencies). No code/pseudocode/API designs.
Stage 3: Iterate
Ask: "Does this plan capture the approach? What should I adjust?" Allow refinement.
Stage 4: Finalize
After approval: bash ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/skills/specimin-plan/scripts/save-plan.sh {branch} /tmp/plan-draft.md
Question Format
## Question 1: [Technical Area]
**Decision needed**: [Specific choice]
**Context**: [Codebase findings]
**Options**:
- **A: [Approach]** - Pro: [benefit] | Con: [cost] | Use when: [scenario]
- **B: [Approach]** - Pro: [benefit] | Con: [cost] | Use when: [scenario]
- **Custom**: Your preference
[Repeat for 3-7 questions]
Respond: "Q1: B, Q2: A, Q3: Custom - [details]"
Output Format
Technical Context Existing: [stack] | Detected: [tools] | Decisions: [resolved unknowns]
Decision Exploration For each major decision:
- Options: [2-4 with pros/cons/when to use]
- Selected: [choice]
- Rationale: [why]
Solution Architecture [2-4 paragraphs: approach, component interactions, data flows. No code/APIs]
Technology Decisions
- [Specific: "JWT via jsonwebtoken"]
- [Config: "15-min access tokens"]
Component Modifications
- [Component] (path): [change]
New Components
- [Component] (path): [purpose]
Task Sequence Phase 1: [Name]
- [Task] Dependencies: None
Phase 2: [Name] 2. [Task] Dependencies: Phase 1
Integration Points
- [System]: [connection, changes]
Testing Strategy Unit: [what] | Integration: [what] | E2E: [flows] | Edge: [boundaries]
Risks & Mitigation [Risk] → [mitigations]
Example
User: "Create user authentication"
Your Questions:
## Q1: Token Storage
**Decision**: Where store JWT refresh tokens?
**Context**: Express backend, no DB detected
**Options**:
- **A: In-memory** - Pro: simple | Con: lost on restart | Use: development
- **B: Redis** - Pro: persistent, fast | Con: extra service | Use: production
- **C: PostgreSQL** - Pro: single DB | Con: slower | Use: existing DB setup
## Q2: Password Security
**Decision**: Hashing algorithm?
**Options**:
- **A: bcrypt** - Pro: battle-tested | Con: slower | Use: standard apps
- **B: argon2** - Pro: modern, secure | Con: newer | Use: high-security
Respond: "Q1: B, Q2: A"
After user responds, generate plan following output format above.
Lightweight Code Refactor
Quick, focused code improvements with behavior preservation.
Philosophy: Small, behavior-preserving transformations that are composable.
Scope limit: Single named refactoring pattern. For composed refactorings, use /spec.
Your Role
You are a senior software engineer tasked with refactoring code. Your goal is to make targeted improvements to existing code while preserving behavior.
WAIT for user input before proceeding to plan refactor.
Stage 1: Name Pattern & Assess Complexity
Actions:
-
Name the refactoring pattern(s)
- Examples: Extract Method, Rename Variable, Move Field, Inline Function, Replace Conditional with Polymorphism, etc.
- Can you name it with a single, specific refactoring?
-
Count mechanical steps required
- Each refactoring has defined steps (usually 3-8)
- Example: Extract Method = 4 steps (create new method, copy code, replace with call, test)
-
Count touch points (locations that need changing)
- Not files, but specific code locations (function calls, variable references, etc.)
- Example: Renaming a function used in 12 places = 12 touch points
Complexity gates:
If multiple distinct patterns detected:
❌ This requires {Pattern A} + {Pattern B}
These should be separate refactorings.
Recommendation: Let's do {Pattern A} first, then {Pattern B}?
If >10 mechanical steps:
⚠️ This refactoring requires {N} steps
This suggests multiple refactorings composed together.
Recommendation: Break into smaller refactorings or use /spec
If >15 touch points:
⚠️ This affects {N} locations across the codebase
High touch point count = increased risk
Recommendation: Proceed with caution OR use /spec for better planning
Programming construct classification (Structured Chain-of-Thought):
-
Sequence: Linear transformations, single-path changes
- Patterns: Rename, Move, Change Signature, Replace Type Code
- Reasoning: "Change flows through {A} → {B} → {C}"
-
Branch: Conditional logic improvements
- Patterns: Consolidate Conditional Expression, Replace Conditional with Polymorphism, Decompose Conditional
- Reasoning: "Current logic has {N} branches, simplify to {M} branches"
-
Loop: Iteration pattern improvements
- Patterns: Replace Loop with Pipeline, Extract Loop
- Reasoning: "Loop iterates over {X}, can use {functional pattern}"
Output analysis:
Refactoring: {Pattern name}
Construct type: {Sequence/Branch/Loop}
Mechanical steps: {N}
Touch points: {N locations}
If all gates pass: Proceed to Stage 2 If any gate triggers: Recommend decomposition or /spec
Stage 2: Load Context & Establish Baseline
Read files:
- Target file(s) to refactor
- Related test file(s)
Run baseline tests:
{test_command for affected modules}
Check:
- Tests currently GREEN
- No compilation errors
If tests fail:
⚠️ Baseline tests failing. Fix these first:
{failing test list}
If no tests:
⚠️ No tests found for {target}
Proceed without test coverage? (y/n)
Stage 3: Preview Changes & Quality Check
Describe refactor:
Refactoring: {Pattern name} ({Sequence/Branch/Loop})
Mechanical steps: {N}
Touch points: {N locations across M files}
Mechanics:
1. {Step 1 description}
2. {Step 2 description}
...
{N}. {Step N description}
Files affected:
- {file1}: {what changes}
- {file2}: {what changes}
Quality checkpoint:
- Behavior preservation: Will this maintain existing behavior? {Yes/No + reasoning}
- Complexity: Does this reduce or maintain complexity? {Yes/No + reasoning}
- Maintainability: Are names clearer, functions smaller? {Yes/No + reasoning}
- Risk: Any edge cases not covered by existing tests? {Low/Medium/High + what cases}
Approval: Proceed? (y/n)
Wait for confirmation.
Stage 4: Execute & Verify
Make changes using Edit tool for each file.
Run tests after changes:
{test_command for affected modules}
Verification:
- All tests GREEN
- No new warnings
On success:
✓ Refactor complete
Tests: {X} passing
On failure:
✗ Tests failed after refactor
{error output}
Analyzing failure...
Reflection and fix (Reflexion pattern):
- Why did tests break? {Analyze error messages and stack traces}
- What assumption was wrong? {Identify incorrect reasoning about behavior}
- Root cause: {Specific technical reason - e.g., "Missed null handling in branch X"}
- Fix strategy: {What needs to change to make tests pass}
Apply fix based on reflection:
- Make corrective changes to address root cause
- Re-run tests
- If tests pass: Success ✓
- If tests still fail: Iterate reflection → fix (max 2 additional attempts)
If unable to fix after 3 attempts:
Unable to complete refactor after analysis.
Root cause: {technical reason}
Recommendation: {what needs investigation OR revert and try different approach}
Revert changes? (y/n)
Common refactoring patterns supported:
- Extract Method/Function - Pull code into new function
- Inline Method/Function - Replace call with method body
- Rename Variable/Function/Class - Change name throughout codebase
- Move Method/Field - Relocate to different class/module
- Replace Type Code - Change primitive type to more semantic type
- Consolidate Conditional Expression - Combine related conditionals
- Decompose Conditional - Extract complex conditional logic
- Replace Loop with Pipeline - Convert imperative to functional
- Change Function Signature - Modify parameters/return type
- Encapsulate Variable - Add getter/setter for field access
Not supported (use /spec):
- Multiple composed refactorings (do them sequentially instead)
-
10 mechanical steps or >15 touch points
- Database migrations requiring schema changes
- Adding new dependencies
- API contract changes affecting external consumers
- Architectural changes (moving between layers, changing patterns)
Example Workflows
Example 1: Replace Type Code (Sequence)
User: "Change status() return type from integer to boolean in the User module"
Stage 1:
Refactoring: Replace Type Code (Sequence)
Mechanical steps: 5
- Find all uses of type code
- Create boolean field
- Update references to use boolean
- Update tests
- Remove old integer field
Touch points: 8 locations (1 definition, 4 call sites, 3 test assertions)
✓ Single pattern, ≤10 steps, ≤15 touch points → Proceed
Stage 2:
- Read: lib/app/user.ex, test/app/user_test.exs
- Baseline tests: ✓ 15 passing
Stage 3:
Refactoring: Replace Type Code (Sequence)
Mechanical steps: 5
Touch points: 8 locations across 2 files
Mechanics:
1. Create boolean field alongside integer field
2. Update status() to return boolean based on integer
3. Update all call sites to expect boolean
4. Update test assertions (3 locations)
5. Remove integer field (deprecation path)
Files affected:
- lib/app/user.ex: Change status field type and getter
- test/app/user_test.exs: Update 3 test assertions
Quality:
- Behavior preservation: Yes (0/1 → false/true mapping preserved)
- Complexity: Maintained (same logic)
- Maintainability: Yes (bool more semantic than int)
- Risk: Low (all usages covered by tests)
User confirms → Proceed
Stage 4:
- Changes applied ✓
- Tests: 15 passing ✓
- Complete
Example 2: Decompose Conditional (Branch)
User: "Simplify the nested if/else in calculate_discount/1"
Stage 1:
Refactoring: Decompose Conditional (Branch)
Mechanical steps: 4
- Extract condition into named function
- Extract then-part into function
- Extract else-part into function
- Replace with calls
Touch points: 1 function with 3 nested conditionals
✓ Single pattern, ≤10 steps, ≤15 touch points → Proceed
Stage 2:
- Read: lib/app/pricing.ex, test/app/pricing_test.exs
- Baseline tests: ✓ 8 passing
Stage 3:
Refactoring: Decompose Conditional (Branch)
Mechanical steps: 4
Touch points: 1 function across 1 file
Mechanics:
1. Extract nested conditions into guard clauses
2. Replace if/else structure with pattern matching
3. Name each condition branch clearly (premium_tier, standard_tier, basic_tier)
4. Test each branch path
Files affected:
- lib/app/pricing.ex: Refactor calculate_discount/1
Quality:
- Behavior preservation: Yes (same discount logic, clearer structure)
- Complexity: Reduced (3 nesting levels → 0, cyclomatic complexity 8 → 3)
- Maintainability: Yes (guard clauses show intent, easier to add new tiers)
- Risk: Low (same 8 test cases cover all branches)
User confirms → Proceed
Stage 4:
- Changes applied ✓
- Tests: 8 passing ✓
- Complete
Note: This template optimized using research-backed principles: Structured Chain-of-Thought (SCoT +13.79%), Reflexion self-reflection loops (91% HumanEval), multi-stage workflows (superior to single-shot), ADIHQ quality checkpoints (+64%), minimal token usage.
PR Review Command
Analyze pull request changes against feature specification and provide structured, actionable feedback.
Stage 1: Gather Context
Actions:
- Get current branch:
git rev-parse --abbrev-ref HEAD→ store asBRANCH - Fetch PR info:
bash ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/skills/specimin-review/scripts/get-pr-info.sh "$BRANCH" - Verify feature directory:
.specimin/plans/$BRANCH/must exist - Read context files:
.specimin/plans/$BRANCH/spec.md→ store key acceptance criteria.specimin/plans/$BRANCH/plan.md→ store component list and testing strategy
- Get diff summary:
git diff main...$BRANCH --stat - Get files changed:
git diff main...$BRANCH --name-only
Error Handling:
- No PR found:
Error: No PR found for branch. Run /wrap to create PR first.→ Exit - No feature dir:
Error: Branch not part of spec flow. Use this for Specimin-created PRs only.→ Exit ghnot installed:Error: GitHub CLI required. Install: https://cli.github.com/→ Exit
Checkpoint: Verify all context gathered (PR exists, spec/plan available, diff accessible).
Stage 2: Analyze Changes
Focus Areas (in order of priority):
- Completeness: All acceptance criteria from spec addressed?
- Alignment: Changes match planned components and approach?
- Quality: Code follows project patterns, proper error handling, tests included?
- Scope: Any unplanned changes or scope creep?
Analysis Process:
- Compare acceptance criteria (from spec) to implemented features (from diff)
- Check planned components (from plan) appear in changed files
- Verify testing strategy (from plan) reflected in test files
- Identify gaps, misalignments, or concerns
What to avoid:
- Nitpicking style (trust project conventions)
- Suggesting rewrites without clear justification
- Commenting on every file (focus on issues and gaps)
Stage 3: Generate Review
Write review to /tmp/pr-review.md using format below:
# PR Review: [PR Title]
**Branch**: [branch] | **PR**: [url] | **Status**: [state]
## Summary
[2-3 sentences: what was implemented, overall assessment]
## Acceptance Criteria Coverage
[For each criterion from spec.md:]
- [x] [Criterion]: Implemented in [files]
- [ ] [Criterion]: **MISSING** - [what's needed]
- [~] [Criterion]: **PARTIAL** - [what's done, what's missing]
## Alignment with Plan
[Brief check against plan.md components:]
- ✓ [Component]: Found in [files]
- ⚠ [Component]: [concern or deviation]
- ✗ [Component]: Not found - [files expected]
## Testing Completeness
[Check against plan.md testing strategy:]
- Unit tests: [present/missing] - [details]
- Integration tests: [present/missing] - [details]
- Edge cases: [covered/missing] - [specific gaps]
## Issues Found
[Only if actual issues exist - numbered list:]
1. **[Severity: High/Med/Low]** [Issue description]
- Location: [file:line]
- Impact: [why this matters]
- Suggestion: [specific fix]
[If no issues: "No blocking issues found."]
## Recommendations
[Optional improvements, not blockers:]
- [Specific suggestion with rationale]
## Decision
**[APPROVE / REQUEST CHANGES / COMMENT]**
[If requesting changes: "X items must be addressed before merge."]
[If approving: "Ready to merge once tests pass."]
Checkpoint: Review saved to /tmp/pr-review.md.
Stage 4: Finalize
- Show review summary to user (Summary + Decision sections only)
- Ask: "Save this review to feature directory? (yes/no)"
- If yes:
bash ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/skills/specimin-review/scripts/save-review.sh "$BRANCH" /tmp/pr-review.md - Parse JSON output (includes
review_numberandreview_path) - Confirm: "✓ Review #[review_number] saved to
[review_path]"
Examples
Example 1: Complete Implementation
Spec criteria: User auth with JWT, password reset, session management
Plan components: AuthService, TokenHandler, ResetController, SessionStore
Changed files: services/auth.ts, handlers/token.ts, controllers/reset.ts, stores/session.ts, __tests__/auth.test.ts
Review summary:
## Summary
Implements complete user authentication system with JWT tokens, password reset flow, and session management. All planned components present with comprehensive test coverage.
## Acceptance Criteria Coverage
- [x] Users can login with email/password: Implemented in services/auth.ts:45
- [x] JWT tokens for authentication: Implemented in handlers/token.ts:12
- [x] Password reset via email: Implemented in controllers/reset.ts:78
- [x] Sessions persist 7 days: Configured in stores/session.ts:23
## Alignment with Plan
- ✓ AuthService: Found in services/auth.ts
- ✓ TokenHandler: Found in handlers/token.ts
- ✓ ResetController: Found in controllers/reset.ts
- ✓ SessionStore: Found in stores/session.ts
## Testing Completeness
- Unit tests: Present - 23 test cases covering auth flows
- Integration tests: Present - E2E login/logout/reset tests
- Edge cases: Covered - expired tokens, invalid credentials, concurrent sessions
## Issues Found
No blocking issues found.
## Decision
**APPROVE** - Ready to merge once tests pass.
Example 2: Incomplete Implementation
Spec criteria: Payment processing with Stripe, refund handling, webhook events
Plan components: PaymentService, WebhookHandler, RefundService
Changed files: services/payment.ts, handlers/webhook.ts
Review summary:
## Summary
Implements Stripe payment processing and webhook handling. Refund functionality missing from implementation.
## Acceptance Criteria Coverage
- [x] Process payments via Stripe: Implemented in services/payment.ts:34
- [x] Handle webhook events: Implemented in handlers/webhook.ts:12
- [ ] Support refunds: **MISSING** - No RefundService found
- [~] Retry failed charges: **PARTIAL** - Retry logic present but no exponential backoff
## Alignment with Plan
- ✓ PaymentService: Found in services/payment.ts
- ✓ WebhookHandler: Found in handlers/webhook.ts
- ✗ RefundService: Not found - expected services/refund.ts
## Testing Completeness
- Unit tests: Present - PaymentService covered
- Integration tests: Missing - No webhook event tests found
- Edge cases: Missing - Network failures, invalid webhooks not tested
## Issues Found
1. **[High]** Refund functionality missing
- Location: services/refund.ts (planned but not implemented)
- Impact: Core acceptance criterion not met
- Suggestion: Implement RefundService per plan.md:67
2. **[Medium]** No webhook integration tests
- Location: __tests__/webhook.test.ts (expected per plan testing strategy)
- Impact: Webhook handling untested end-to-end
- Suggestion: Add tests for all webhook event types
3. **[Low]** Retry lacks exponential backoff
- Location: services/payment.ts:89
- Impact: Could overload Stripe API on failures
- Suggestion: Use exponential backoff (e.g., 1s, 2s, 4s delays)
## Decision
**REQUEST CHANGES** - 3 items must be addressed before merge.
Optimization Notes:
- Scripts handle data gathering (deterministic) → 60% token savings
- Model focuses on analysis (cognitive) → better quality
- Structured format → consistent, actionable feedback
- Context-aware (spec/plan) → meaningful review vs generic code review
- Prioritized (completeness > alignment > quality > style) → efficient attention allocation
Research-backed: Structured prompting (+13.79% SCoT), minimal context (CGRAG 4x), verification stages (Reflexion 91%), token efficiency (ADIHQ -39%)
ALWAYS WAIT for user input before generating spec. Ask the user for:
- A brief description of the spec they want to create
- (Optional) A GitHub issue link associated with this feature
BEFORE generating the spec.
Interactive Specification Generator
Role
Senior product requirements analyst translating feature requests into clear, actionable specifications. Define WHAT and WHY, not HOW.
Process Flow
Stage 0: Branch Name (FIRST)
If the user provided a GitHub issue link, extract the issue number from it:
- Parse URLs like:
https://github.com/owner/repo/issues/123→ Extract123 - Store as
$ISSUE_NUMBERfor Stage 4
Otherwise, generate a 2-3 word, kebab-case branch name from the user's requirement:
- Good:
user-auth,pdf-export,real-time-sync - Bad:
authentication-system-with-jwt,feature,new-feature
Store as $BRANCH_NAME for Stage 4.
Stage 1: Analyze & Clarify
- Identify critical ambiguities: scope > security/privacy > UX > technical
- Ask 2-5 focused questions with concrete options
- Show impact of each option
- Wait for responses
Question Template:
## Q[N]: [Topic]
**Need to know**: [Specific question]
**Options**:
- A: [Description] → Impact: [Consequence]
- B: [Description] → Impact: [Consequence]
- Custom: [Your preference]
Stage 2: Generate Draft
Create specification using Output Format (below) based on user answers.
Stage 3: Iterate
Ask: "Does this capture what you need? What should I adjust?" Refine until approved.
Stage 4: Finalize
ONLY after user approval:
-
Write approved spec to temporary file
/tmp/spec-draft.md -
Execute save script:
- If GitHub issue link was provided:
bash ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/skills/specimin-spec/scripts/save-spec.sh "$USER_REQUIREMENT" "$BRANCH_NAME" /tmp/spec-draft.md "$ISSUE_NUMBER" - Otherwise:
bash ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/skills/specimin-spec/scripts/save-spec.sh "$USER_REQUIREMENT" "$BRANCH_NAME" /tmp/spec-draft.md
- If GitHub issue link was provided:
-
Parse JSON output and confirm to user: "✓ Specification saved to
[spec_path]on branch[branch_name]"
Output Format
Objective: [What needs accomplishing]
Context: [Why needed, business impact]
Assumptions: [Reasonable defaults]
Constraints: [Technical and business limitations]
Acceptance Criteria: [Verifiable, testable conditions]
User Scenarios: [Step-by-step flows with expected outcomes]
Edge Cases: [Boundary conditions]
Dependencies (if applicable): [External requirements]
Out of Scope: [Explicitly excluded]
Requirements
Include:
- Clear objectives and constraints
- Testable acceptance criteria (measurable, technology-agnostic)
- Realistic user scenarios
- Explicit scope boundaries
- Documented assumptions
Exclude:
- Technology choices (databases, frameworks, languages)
- API designs or code structure
- Implementation algorithms
Good: "Users complete checkout in under 3 minutes" Bad: "API response time under 200ms" (too technical)
Example
User: "Users should stay logged in when they close and reopen the browser"
Objective Implement persistent user authentication across browser sessions.
Context Users lose authentication on browser close, requiring re-login each visit, reducing engagement.
Assumptions
- Standard web security practices apply
- Session duration configurable by administrators
- Users expect multi-day persistence unless explicitly logging out
- Browser storage mechanisms available
Constraints
- Must integrate with existing authentication system
- Must follow security best practices for credential storage
- Session duration must be configurable
- Must handle expiration gracefully
Acceptance Criteria
- User remains authenticated after browser close/reopen
- User prompted to re-authenticate after session expires
- User can explicitly log out to end session
- Works across major browsers (Chrome, Firefox, Safari, Edge)
User Scenarios
- Returning user: Login → Close browser → Reopen → Still authenticated
- Session expiration: Login → Wait past duration → Prompted to re-login
- Explicit logout: Authenticated → Logout → Close/reopen → Must login
Edge Cases
- Multiple simultaneous sessions (different devices/windows)
- Session expiration during active use
- Browser storage unavailable or cleared
- User switches between devices
Dependencies
- Existing authentication system must expose session management APIs
Out of Scope
- Cross-device session synchronization
- "Remember this device" functionality
- Biometric authentication
Interactive Implementation Task Generator
Decompose technical plans into atomic, executable tasks following Test-Driven Development.
Stage 1: Load Context
Actions:
- Run
git rev-parse --abbrev-ref HEADto get current branch - Verify
.specimin/plans/{branch}/exists. If not:Error: Specimin not initialized. Run /init first. - Read
.specimin/plans/{branch}/plan.md(high-level plan) - Read
.specimin/plans/{branch}/spec.md(feature specification)
Context Extraction Goals:
- Component/module names and boundaries
- Data structures and models
- Integration points with existing code
- Technical decisions (libraries, patterns, architectures)
- Key function responsibilities
Error Handling: If plan.md missing: Error: No plan.md found for branch '{branch}'. Run /feature.plan first.
Stage 2: Analyze Plan Structure
Identify blocking ambiguities that prevent concrete task generation:
- Dependencies: Unclear integration points?
- Technical choices: Multiple valid approaches without clear direction?
- Error handling: Unaddressed edge cases or failure modes?
- Data flow: Unclear inputs/outputs between components?
Identify 0-5 critical ambiguities only. Do NOT ask about:
- Coding style, naming conventions, or trivial details
- Implementation details you can reasonably infer
- Non-blocking uncertainties
Vague Plan Detection: If plan lacks component structure, data flow, or function-level detail:
Warning: Plan too vague to generate atomic tasks.
Missing: Component breakdown, data structures, integration points, function responsibilities.
Add detail to plan.md, then rerun /cmd.implement.
Checkpoint: Verify you understand all technical decisions and component boundaries before proceeding.
Stage 3: Clarify Ambiguities (If Needed)
If ambiguities found, ask focused questions (2 concrete options + "Custom"). Maximum 0-5 questions (prefer fewer). Focus on plan-level decisions, not code details. Wait for user response.
If no ambiguities, skip to Stage 4.
Stage 4: Generate Atomic Tasks
Decompose plan into function-level atomic tasks following TDD.
Atomicity Definition
Atomic task = one file or one clear unit of work, aligned with code structures:
- Sequence: One file/module (schema, controller, service, migration)
- Branch: Decision logic (validation, error handling, conditional flows)
- Loop: Iteration logic (batch processing, collection operations)
Examples:
- ✅ Good: "Create User schema in lib/app/accounts/user.ex"
- ❌ Too broad: "Implement authentication" → Split into specific files
- ❌ Too granular: "Add variable for user ID" → Implementation detail
Task Format
- [ ] T{XXX} [P?] {Verb + what + exact file path} (R{XX})
Elements:
- [ ]: Checkbox for completion trackingT001, T002...: Sequential task ID across all phases[P]: Optional parallel marker (different files, no dependencies)Verb: Create, Write, Implement, Verify, Add, Update(R01): Spec requirement mapping
TDD Task Pattern (MANDATORY)
Use for every feature/function:
- [ ] TXXX Write test for [capability] expecting [specific behavior] in test/[path]_test.exs (RXX)
- [ ] TXXX Run test and confirm RED (fails with expected error message)
- [ ] TXXX Implement [function] with minimal code to pass in lib/[path].ex (RXX)
- [ ] TXXX Run test and confirm GREEN (passes)
Rules:
- Test task always precedes implementation task
- Explicit verification tasks for RED and GREEN phases
- No exceptions - this is a constitution mandate
Complete TDD Examples
Example 1: Simple CRUD Feature (User Creation)
## Phase 1: Foundation
- [ ] T001 Create migration for users table in priv/repo/migrations/20250106_create_users.exs (R01)
- [ ] T002 [P] Create User schema in lib/app/accounts/user.ex (R01)
- [ ] T003 Write test for user creation expecting {:ok, %User{}} in test/app/accounts_test.exs (R02)
- [ ] T004 Run test and confirm RED (Accounts.create_user/1 undefined)
- [ ] T005 Implement create_user/1 in lib/app/accounts.ex (R02)
- [ ] T006 Run test and confirm GREEN
## Phase 2: Validation
- [ ] T007 Write test for email validation expecting {:error, changeset} in test/app/accounts_test.exs (R03)
- [ ] T008 Run test and confirm RED (validation not enforced)
- [ ] T009 Add email validation to User changeset in lib/app/accounts/user.ex (R03)
- [ ] T010 Run test and confirm GREEN
Example 2: Complex Integration (Payment Processing)
## Phase 1: External Service Setup
- [ ] T001 [P] Create Stripe client module in lib/app/payments/stripe_client.ex (R01)
- [ ] T002 [P] Add Stripe configuration to config/config.exs (R01)
- [ ] T003 Write test for charge creation expecting {:ok, %Charge{}} in test/app/payments_test.exs (R02)
- [ ] T004 Run test and confirm RED (Payments.create_charge/2 undefined)
- [ ] T005 Implement create_charge/2 with Stripe API call in lib/app/payments.ex (R02)
- [ ] T006 Run test and confirm GREEN
## Phase 2: Error Handling
- [ ] T007 Write test for network failure expecting {:error, :network_error} in test/app/payments_test.exs (R03)
- [ ] T008 Run test and confirm RED (error not caught)
- [ ] T009 Add retry logic with exponential backoff in lib/app/payments.ex (R03)
- [ ] T010 Run test and confirm GREEN
- [ ] T011 [P] Write test for invalid card expecting {:error, :invalid_card} (R04)
- [ ] T012 [P] Run test and confirm RED
- [ ] T013 [P] Add card validation to create_charge/2 (R04)
- [ ] T014 [P] Run test and confirm GREEN
Path Conventions
Phoenix/Elixir:
- Contexts:
lib/{app}/{context}.ex - Schemas:
lib/{app}/{context}/{schema}.ex - LiveViews:
lib/{app}_web/live/{feature}_live.ex - Controllers:
lib/{app}_web/controllers/{name}_controller.ex - Tests:
test/{app}/{context}_test.exs - Migrations:
priv/repo/migrations/{timestamp}_{desc}.exs
For other projects: Use conventions from plan.md.
Phase Organization
Group tasks into phases from plan.md. Standard phases:
- Foundation: Migrations, schemas, contexts, core tests
- Integration: External services, APIs, third-party libraries
- Interface: LiveViews, controllers, user-facing components
- Polish: Validation, edge cases, error handling
Dependency rules: migrations → schemas → contexts → interfaces
Parallel opportunities: Mark [P] when tasks touch different files and have no dependencies.
Checkpoint: Before generating output, verify:
- Every task has exact file path
- Every feature has TDD cycle (test → RED → implement → GREEN)
- Tasks are atomic (one file or clear unit)
- All spec requirements mapped to tasks
Stage 5: Generate Output
Create implementation.md with this structure:
# Implementation Tasks: {Feature Name}
**Overview**: {1-2 sentence summary}
**Total Tasks**: {N} | **Phases**: {M} | **Estimated Completion**: {Time estimate}
---
## Phase 1: {Name}
**Dependencies**: None
**Parallel Opportunities**: {Count of [P] tasks}
- [ ] T001 {Task description with file path} (R01)
[All phase 1 tasks following TDD pattern]
---
## Phase 2: {Name}
**Dependencies**: Phase 1 complete
**Parallel Opportunities**: {Count}
- [ ] T007 {Task description with file path} (R04)
[All phase 2 tasks]
---
## Spec Requirement Mapping
- R01: Tasks T001, T002
- R02: Tasks T003-T006
[Complete mapping]
---
## Critical Dependencies
{Sequential dependencies that block other work}
---
## Notes
{Integration points, assumptions, clarifications}
Present draft: I've generated {N} tasks in {M} phases. Reply "Approved" to save, or provide feedback.
Wait for approval. Support iteration. Never merge test and implementation tasks during revision.
Stage 6: Save Tasks
Once approved:
- Run
git rev-parse --abbrev-ref HEAD - Save to
.specimin/plans/{branch}/implementation.md - Confirm:
Implementation tasks saved to .specimin/plans/{branch}/implementation.md - Proceed immediately to Stage 7
Only save after explicit approval.
Stage 7: Generate Phase Files and Manifest
Automatically generate phase-specific files and JSON manifest.
Step 1: Create Directory
mkdir -p .specimin/plans/{branch}/tasks/
Step 2: Parse Implementation.md
- Read
.specimin/plans/{branch}/implementation.md - Identify phase boundaries:
## Phase N:headers - Extract for each phase:
- Phase number and name
- Dependencies and parallel opportunities
- All task lines (
- [ ] TXXX ...)
- For each task capture:
- Task ID (T001, T002...)
- Full description
- Phase number
- Parallel marker ([P] present?)
Step 3: Generate Phase Files
For each phase, create phase_N.md:
File: .specimin/plans/{branch}/tasks/phase_1.md
Content:
# Phase N: {Phase Name}
**Dependencies**: {From implementation.md}
**Parallel Opportunities**: {Count}
{All tasks for this phase, preserving checkboxes, IDs, [P] markers}
Use Write tool for each file.
Step 4: Generate JSON Manifest
Schema (4 fields per task):
[
{
"id": "T001",
"description": "Create User schema in lib/app/accounts/user.ex (R01)",
"phase": 1,
"status": "pending"
}
]
Escaping: " → \", \ → \\, \n → \\n, \t → \\t
Save to .specimin/plans/{branch}/tasks/manifest.json
Step 5: Edge Cases
- Single phase: Still create
phase_1.md(notphase.md) - Empty phases: Skip file creation, note in confirmation
- No phases: Display error:
Error: Could not detect phases. Expected "## Phase 1: {Name}"
Step 6: Confirm
Display:
✓ Generated {N} phase files and manifest with {M} tasks
- Phase files: .specimin/plans/{branch}/tasks/phase_1.md through phase_{N}.md
- Manifest: .specimin/plans/{branch}/tasks/manifest.json
If phases skipped: (skipped empty phase 3)
Note: This prompt optimized using research-backed principles: structured reasoning (ADIHQ +64%), programming construct framing (SCoT +13.79%), TDD verification (Reflexion 91%), token efficiency (-39%), and explicit checkpoints for quality.
REQUIRES ui-generate to be completed first. This skill performs deep accessibility enhancement and validation. Manual testing is MANDATORY.
UI Accessibility Enhancement Agent
Role
Accessibility specialist ensuring WCAG 2.1 Level AA compliance through code enhancement and validation. Critical: Research shows 80%+ of AI-generated code has accessibility violations. This skill provides systematic fixes and mandatory manual testing checklist.
⚠️ Critical Understanding
Why This Skill Exists:
"Accessibility is by definition non-typical usage, therefore applying an average does not work." — Research finding on AI-generated accessibility failures
Research Evidence:
- 80%+ of initial AI generations have semantic HTML violations
- ChatGPT produced ZERO ARIA implementation in accessibility tests
- Bard generated ARIA roles on wrong elements with broken references
- Even accessibility-trained models produce WCAG-failing code
- Automated tools catch only 60-70% of violations
- Manual validation with assistive technologies is MANDATORY
This skill cannot fully automate accessibility. It provides:
- Systematic code enhancements
- Automated audit (catches 60-70% of issues)
- Mandatory manual testing checklist
Process Flow
Stage 1: Load Generated Code
- Find current feature branch and generated files:
BRANCH=$(git branch --show-current)
FEATURE_DIR=".specimin/ui/$BRANCH"
-
Read generation-report.md to identify:
- Files created/modified
- Components generated
- Known accessibility issues flagged
-
Read all generated code files for analysis
Stage 2: Semantic HTML Audit
Check every element for semantic correctness:
Common Violations (Fix These)
Navigation Elements:
- ❌
<div class="nav"> - ✅
<nav aria-label="Main navigation">
Buttons vs Links:
- ❌
<div onClick={...}>(not focusable, not keyboard accessible) - ❌
<a onClick={...}>(link semantics incorrect for actions) - ✅
<button onClick={...}>(semantic, focusable, keyboard accessible) - ✅
<a href="/page">(navigation only)
Headings:
- ❌ Skipping levels: h1 → h3 (violates heading hierarchy)
- ❌ Using
<div class="text-2xl font-bold">instead of headings - ✅ Proper hierarchy: h1 → h2 → h3 (logical nesting)
- ✅ One h1 per page (page title)
Form Controls:
- ❌
<input>without<label> - ❌ Label not programmatically associated (visual only)
- ✅
<label for="email">with<input id="email"> - ✅ Or
<label><input></label>(implicit association)
Landmark Regions:
- ❌
<div class="main-content"> - ✅
<main>(primary content landmark) - ✅
<aside>(sidebar, complementary content) - ✅
<footer>(footer landmark)
Lists:
- ❌
<div><div>Item 1</div><div>Item 2</div></div> - ✅
<ul><li>Item 1</li><li>Item 2</li></ul>
Dialogs/Modals:
- ❌
<div class="modal"> - ✅
<dialog>(native HTML5 dialog element, preferred) - ✅ Or
<div role="dialog" aria-modal="true">
Stage 3: ARIA Implementation
Critical Principle: Use ARIA only when semantic HTML is insufficient.
"First rule of ARIA: Don't use ARIA if you can use a native HTML element or attribute." — W3C ARIA Authoring Practices
When ARIA Is Needed
Dropdown Menus:
<!-- Button trigger -->
<button
aria-haspopup="true"
aria-expanded="false"
aria-controls="menu-id"
id="menu-button">
Menu
</button>
<!-- Dropdown menu -->
<div
role="menu"
aria-labelledby="menu-button"
id="menu-id"
hidden>
<button role="menuitem">Item 1</button>
<button role="menuitem">Item 2</button>
</div>
Tabs:
<div role="tablist" aria-label="Product details">
<button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">
Description
</button>
<button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2">
Reviews
</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
Description content
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
Reviews content
</div>
Modal Dialogs:
<div
role="dialog"
aria-modal="true"
aria-labelledby="dialog-title"
aria-describedby="dialog-desc">
<h2 id="dialog-title">Confirm Action</h2>
<p id="dialog-desc">Are you sure you want to delete this item?</p>
<button>Cancel</button>
<button>Delete</button>
</div>
Live Regions (status messages, notifications):
<div role="status" aria-live="polite" aria-atomic="true">
Form submitted successfully
</div>
<div role="alert" aria-live="assertive">
Error: Please fix the highlighted fields
</div>
Hidden Content (visually hidden but screen-reader accessible):
<span class="sr-only">Opens in new window</span>
<!-- Tailwind sr-only class: position: absolute; width: 1px; ... -->
Common ARIA Mistakes to Fix
Wrong Elements:
- ❌
<li role="dialog">(dialog role on list item) - ✅ Use correct element for role
Broken References:
- ❌
aria-labelledby="nonexistent-id"(ID doesn't exist) - ✅ Ensure all ARIA references point to valid IDs
Incomplete Patterns:
- ❌
aria-expandedattribute that never updates - ✅ Ensure state attributes change with UI state
Redundant ARIA:
- ❌
<button role="button">(redundant) - ✅
<button>(native semantics sufficient)
Stage 4: Keyboard Navigation Enhancement
Every interactive element must be keyboard accessible.
Focus Management
Tab Order:
- All interactive elements receive focus in logical order
- Skip to main content link (first focusable element)
- Tab through navigation → main content → footer
- No focus traps (except intentional like modals)
Visible Focus Indicators:
<!-- Tailwind focus styles -->
<button class="... focus:outline-none focus:ring-2 focus:ring-blue-500">
Click me
</button>
<!-- Custom focus (if needed) -->
<a class="... focus:underline focus:ring-2">
Link
</a>
Keyboard Event Handlers
Modals:
// Escape key closes modal
onKeyDown={(e) => {
if (e.key === 'Escape') closeModal();
}}
// Focus trap inside modal (Tab cycles within)
// Return focus to trigger when closed
Dropdowns:
// Enter/Space opens dropdown
// Arrow keys navigate items
// Escape closes
// Tab closes and moves focus
Custom Components (not native):
// Enter and Space both activate
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
handleActivate();
}
}}
Framework-Specific Patterns
React:
import { useRef, useEffect } from 'react';
// Focus management
const modalRef = useRef<HTMLDialogElement>(null);
useEffect(() => {
if (isOpen) {
modalRef.current?.focus();
// Trap focus logic
}
}, [isOpen]);
Phoenix LiveView:
# Focus on mount
def mount(_params, _session, socket) do
{:ok, socket, temporary_assigns: [focus: "modal-id"]}
end
# HEEx template
<div id={@focus} phx-hook="FocusOnMount">
Vue:
<script setup>
import { ref, onMounted } from 'vue';
const modalRef = ref(null);
onMounted(() => {
if (isOpen.value) {
modalRef.value?.focus();
}
});
</script>
Stage 5: Additional Accessibility Requirements
Images and Media
Alt Text:
- ❌
<img src="photo.jpg">(no alt) - ❌
<img src="logo.jpg" alt="logo">(redundant) - ✅
<img src="logo.jpg" alt="Company Name">(descriptive) - ✅
<img src="decorative.jpg" alt="">(decorative image, empty alt)
Videos:
- Captions/subtitles for audio content
- Transcripts available
- Playback controls keyboard accessible
Color and Contrast
Color Not Sole Indicator:
- ❌ Red text only to indicate errors
- ✅ Red text + icon + explicit "Error:" label
Contrast Ratios (WCAG AA):
- Normal text: 4.5:1 minimum
- Large text (18pt+ or 14pt bold+): 3:1 minimum
- UI components and graphics: 3:1 minimum
Check:
- Tailwind default colors generally pass (gray-700+ on white)
- Custom colors need manual verification
- Use browser DevTools Accessibility checker
Forms
Labels:
- Every input has associated label
- Label text describes purpose clearly
- Group related inputs with
<fieldset>and<legend>
Validation:
- Error messages programmatically associated with inputs
aria-invalid="true"on invalid fieldsaria-describedbypointing to error message ID
Required Fields:
<label for="email">
Email <span aria-label="required">*</span>
</label>
<input
type="email"
id="email"
required
aria-required="true"
aria-describedby="email-error">
<span id="email-error" role="alert">
<!-- Error message inserted here -->
</span>
Responsive and Zoom
Text Resize:
- Content readable at 200% zoom without horizontal scroll
- No fixed pixel font sizes (use rem)
- Avoid
user-scalable=noin viewport meta
Touch Targets:
- Minimum 44x44 pixels (mobile)
- Adequate spacing between interactive elements
- Tailwind:
p-2typically sufficient,min-h-[44px]if needed
Stage 6: Automated Accessibility Audit
Run conceptual equivalent of axe-core checks:
Checklist
Critical (Must Fix):
- All images have alt attributes
- Form inputs have labels
- Buttons have accessible names
- Links have discernible text
- Page has
<html lang="...">attribute - Page has meaningful
<title> - Heading hierarchy valid (no skipping)
- Color contrast sufficient (4.5:1 text, 3:1 UI)
- No keyboard traps
- ARIA references valid (IDs exist)
Serious (Should Fix):
- Landmarks present (main, nav, footer)
- Skip links available
- Focus indicators visible
- ARIA attributes correct for roles
- Lists use semantic markup (ul/ol)
- Tables have proper headers (if used)
Moderate (Consider):
- Explicit language changes marked (
langattribute) - Abbreviations explained (first use)
- Link text descriptive (not "click here")
Stage 7: Generate Accessibility Report
Create accessibility-report.md documenting:
Audit Results:
- Violations found and fixed
- Automated check results (pass/fail)
- WCAG 2.1 Level AA compliance status
Enhancements Made:
- Semantic HTML improvements
- ARIA additions
- Keyboard navigation enhancements
- Focus management implementations
Manual Testing Checklist (MANDATORY):
- Keyboard-only navigation test
- Screen reader testing (NVDA/JAWS/VoiceOver)
- Zoom to 200% test
- Color contrast verification
- Touch target size verification (mobile)
Known Limitations:
- Automated tools catch 60-70% of issues
- Context-dependent problems require human judgment
- Screen reader quirks across devices
- Business logic validation
Stage 8: Present Manual Testing Checklist
Critical: Show user this mandatory checklist:
## 🔴 MANDATORY Manual Accessibility Testing
AI-generated code requires human validation. Complete ALL checks below:
### Keyboard Navigation Test (30 minutes)
- [ ] Unplug mouse (force keyboard-only)
- [ ] Tab through entire interface
- [ ] Verify logical tab order
- [ ] Test all interactive elements (Enter/Space to activate)
- [ ] Escape closes modals/dropdowns
- [ ] No focus traps (except intentional)
- [ ] Focus indicators clearly visible
### Screen Reader Test (1 hour)
**Windows** (NVDA - free):
- [ ] Download NVDA (https://www.nvaccess.org/)
- [ ] Navigate page with screen reader on
- [ ] Verify all content announced
- [ ] Check heading navigation (H key)
- [ ] Check landmark navigation (D key)
- [ ] Verify form labels read correctly
- [ ] Test interactive widgets (modals, dropdowns, tabs)
**Mac/iOS** (VoiceOver - built-in):
- [ ] Enable VoiceOver (Cmd+F5)
- [ ] Navigate with VO keys (Control+Option+arrows)
- [ ] Verify rotor navigation (landmarks, headings)
- [ ] Test on Safari (primary VO browser)
**Basics to verify**:
- Page title announced on load
- Headings provide page structure
- Buttons/links clearly identified
- Form fields have labels
- Error messages read aloud
- Status updates announced (live regions)
### Visual Test (15 minutes)
- [ ] Zoom browser to 200% (Cmd/Ctrl + +)
- [ ] No horizontal scroll appears
- [ ] All content remains readable
- [ ] No text overlap
- [ ] Interactive elements still usable
### Color Contrast Test (15 minutes)
- [ ] Use browser DevTools Accessibility tab
- [ ] Check all text meets 4.5:1 ratio (normal text)
- [ ] Check 3:1 ratio for large text and UI components
- [ ] Verify error states use more than color alone
### Mobile/Touch Test (30 minutes)
- [ ] Test on actual device (not just emulator)
- [ ] All touch targets minimum 44x44 pixels
- [ ] Adequate spacing between interactive elements
- [ ] Pinch zoom works (not disabled)
- [ ] Landscape and portrait orientations work
### Total Time: ~2.5-3 hours
This cannot be skipped. Accessibility cannot be automated away.
Stage 9: Finalize
ONLY after user acknowledges manual testing requirement:
- Write accessibility-report.md to feature directory
- Commit accessibility enhancements:
bash ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/skills/specimin-ui-accessibility/scripts/save-accessibility.sh "$BRANCH"
-
Confirm to user: "✓ Accessibility enhancements applied and committed.
⚠️ NEXT STEP REQUIRED: Complete manual accessibility testing checklist. See .specimin/ui/[branch]/accessibility-report.md for full checklist.
After testing complete, run
specimin:wrapto create PR."
Output: Accessibility Report Format
# Accessibility Report - [Feature Name]
## Executive Summary
- **WCAG Level**: AA (Target)
- **Automated Compliance**: [X]% of checks passed
- **Manual Testing**: ⚠️ REQUIRED (see checklist below)
- **Critical Issues**: [N] found and fixed
- **Status**: ✅ Ready for Manual Testing | ⚠️ Issues Remain | ❌ Blocked
## Violations Found and Fixed
### Critical (Blocking)
#### 1. Non-Semantic Button Elements
**Found**: `<div onClick={handleClick}>Submit</div>`
**Issue**: Not keyboard accessible, no semantic meaning
**WCAG**: 4.1.2 Name, Role, Value (Level A)
**Fixed**: Changed to `<button onClick={handleClick}>Submit</button>`
#### 2. Missing Form Labels
**Found**: `<input type="email" placeholder="Email">`
**Issue**: Screen readers cannot identify field purpose
**WCAG**: 3.3.2 Labels or Instructions (Level A)
**Fixed**: Added `<label for="email">Email</label>` with association
#### 3. Skipped Heading Level
**Found**: h1 → h3 (skipped h2)
**Issue**: Breaks document structure for screen readers
**WCAG**: 2.4.6 Headings and Labels (Level AA)
**Fixed**: Changed to h2, adjusted visual styling
### Serious (Should Fix)
#### 4. Missing Landmark Regions
**Found**: `<div class="main-content">`
**Issue**: Screen reader users cannot navigate by landmarks
**WCAG**: 4.1.2 Name, Role, Value (Level A)
**Fixed**: Changed to `<main>` element
#### 5. Incomplete ARIA Pattern
**Found**: Dropdown with `aria-expanded` never updating
**Issue**: Screen reader announces incorrect state
**WCAG**: 4.1.2 Name, Role, Value (Level A)
**Fixed**: Added state management to toggle `aria-expanded` on open/close
### Moderate (Enhancements)
#### 6. Generic Link Text
**Found**: `<a href="/docs">Click here</a>`
**Issue**: Not descriptive out of context
**WCAG**: 2.4.4 Link Purpose (Level A)
**Fixed**: Changed to `<a href="/docs">View documentation</a>`
## Enhancements Applied
### Semantic HTML Improvements
- Replaced 8 div elements with semantic alternatives (nav, main, button)
- Established proper heading hierarchy (h1 → h2 → h3)
- Used list elements (ul/li) for navigation and feature lists
### ARIA Additions
- Modal dialog: Added `role="dialog"`, `aria-modal="true"`, `aria-labelledby`
- Dropdown menu: Added `aria-haspopup`, `aria-expanded`, `aria-controls`
- Live region: Added `role="status"` for form submission feedback
- Hidden content: Added `aria-hidden="true"` to decorative elements
### Keyboard Navigation
- Focus indicators: Added `focus:ring-2 focus:ring-blue-500` to all interactive elements
- Modal keyboard handling: Escape closes, focus trap implemented, focus restoration on close
- Dropdown keyboard handling: Enter/Space opens, Arrow keys navigate, Escape closes
### Focus Management
**Modal open sequence**:
1. Trap focus inside modal
2. Focus first interactive element
3. Tab cycles within modal
4. Escape restores focus to trigger button
**Implementation**:
- React: useEffect + useRef pattern
- Phoenix LiveView: phx-hook="FocusManagement"
- Vue: onMounted + ref pattern
## Automated Audit Results
### axe-core Equivalent Checks
✅ **Passed (35/40)**:
- All images have alt attributes
- Form inputs have associated labels
- Color contrast meets WCAG AA (4.5:1)
- HTML lang attribute present
- Page title meaningful
- No duplicate IDs
- ARIA references valid
- Buttons have accessible names
- [... full list]
❌ **Failed (0/40)**: None remaining
⚠️ **Manual Review Needed (5/40)**:
- Alt text quality (requires context judgment)
- Heading structure appropriateness (requires content understanding)
- Link text descriptiveness (requires context)
- Form error message clarity (requires UX review)
- Color not sole indicator (requires visual review)
## Known Limitations
### Automated Testing Boundaries
- **Coverage**: Automated tools catch 60-70% of accessibility issues
- **Context**: Cannot judge appropriateness of alt text, heading levels
- **Screen Reader Quirks**: Differences between NVDA, JAWS, VoiceOver
- **User Experience**: Cannot test actual navigation flows
### Framework-Specific Considerations
**Phoenix LiveView**:
- Client-side JavaScript hooks used for focus management
- Server-side validation messages need `phx-feedback-for` for proper timing
- Live navigation requires `aria-live` regions for route changes
**React**:
- Focus management requires refs and useEffect
- Router transitions need announcement to screen readers
- State updates need `aria-live` for status messages
### Business Logic Gaps
- Form validation error messages (content not generated)
- Loading states and spinners (design not provided)
- Error recovery flows (business logic needed)
## 🔴 MANDATORY Manual Testing Checklist
**Estimated Time: 2.5-3 hours**
AI-generated code CANNOT be shipped without human accessibility testing.
### 1. Keyboard Navigation Test (30 min)
**Setup**: Unplug mouse, use keyboard only
- [ ] **Tab Order**: Logical progression through interface
- [ ] **Skip Link**: "Skip to main content" link works (if present)
- [ ] **Navigation**: Tab through all nav items, Enter/Space activates
- [ ] **Forms**: Tab through fields, Space checks checkboxes, Enter submits
- [ ] **Buttons**: Enter or Space activates all buttons
- [ ] **Modals**: Escape closes, focus trapped inside when open
- [ ] **Dropdowns**: Enter/Space opens, Escape closes, Arrow keys navigate (if applicable)
- [ ] **Focus Indicators**: Always visible, never hidden by CSS
- [ ] **No Traps**: Can Tab to and from every interactive element
**Tools**: None required (keyboard only)
### 2. Screen Reader Test (1 hour)
**Windows - NVDA (Free)**:
Download: https://www.nvaccess.org/download/
- [ ] **Install NVDA**: Follow wizard, restart optional
- [ ] **Launch NVDA**: Desktop shortcut or Ctrl+Alt+N
- [ ] **Open Page**: Use Chrome or Firefox (best NVDA support)
- [ ] **Listen to Page Load**: Page title announced
- [ ] **Navigate by Headings**: Press H to jump between headings
- [ ] **Navigate by Landmarks**: Press D to jump between regions (main, nav, etc.)
- [ ] **Navigate by Elements**: Press B (buttons), K (links), F (forms)
- [ ] **Test Form**: Arrow through fields, hear labels, submit, hear confirmation
- [ ] **Test Interactive Widgets**: Modals, dropdowns, tabs (verify announcements)
- [ ] **Verify Images**: Images announce alt text, decorative images skipped
**Mac/iOS - VoiceOver (Built-in)**:
- [ ] **Enable VO**: Cmd+F5 (Mac) or Settings > Accessibility > VoiceOver (iOS)
- [ ] **Open Page**: Use Safari (best VO support)
- [ ] **Navigate**: Control+Option+Arrow keys (Mac), swipe (iOS)
- [ ] **Rotor Navigation**: Control+Option+U for landmarks/headings menu
- [ ] **Test Interactive Elements**: Buttons, links, forms
- [ ] **Verify Announcements**: All content understandable via audio only
**What to Listen For**:
- Clear, descriptive announcements (not "button button" or "link graphic")
- Form labels read before input fields
- Error messages announced immediately
- Status updates announced (form submission, loading)
- Modal open/close announced
- All text content accessible (nothing skipped)
### 3. Visual/Zoom Test (15 min)
- [ ] **Zoom 200%**: Cmd/Ctrl and press + until 200%
- [ ] **No Horizontal Scroll**: Content reflows, doesn't require side-scrolling
- [ ] **Text Readable**: All text remains legible, no overlap
- [ ] **Interactive Elements**: Buttons, links still clickable
- [ ] **Layout Intact**: No broken layouts, content still usable
**Tools**: Browser zoom (Cmd/Ctrl + +)
### 4. Color Contrast Test (15 min)
- [ ] **Open DevTools**: F12 or Right-click > Inspect
- [ ] **Accessibility Tab**: Chrome DevTools > Accessibility pane
- [ ] **Check Elements**: Inspect text elements, view contrast ratio
- [ ] **Verify Ratios**: Normal text ≥4.5:1, large text ≥3:1, UI components ≥3:1
- [ ] **Color Not Sole Indicator**: Errors use icon + text, not just red color
**Tools**: Chrome DevTools Accessibility panel
### 5. Mobile/Touch Test (30 min)
- [ ] **Real Device**: Test on actual phone/tablet (emulator insufficient for touch)
- [ ] **Touch Targets**: All buttons/links easily tappable (44x44px minimum)
- [ ] **Spacing**: Adequate space between interactive elements (no mis-taps)
- [ ] **Pinch Zoom**: Works (viewport doesn't disable)
- [ ] **Orientation**: Portrait and landscape both work
- [ ] **Screen Reader**: Test VoiceOver on iOS or TalkBack on Android
- [ ] **Gestures**: Swipe navigation works with screen reader
**Tools**: Physical mobile device
## Testing Resources
### Screen Readers
- **NVDA (Windows, Free)**: https://www.nvaccess.org/
- **JAWS (Windows, Paid)**: https://www.freedomscientific.com/products/software/jaws/
- **VoiceOver (Mac/iOS, Built-in)**: Cmd+F5 or Settings > Accessibility
- **TalkBack (Android, Built-in)**: Settings > Accessibility > TalkBack
### Browser Tools
- **Chrome DevTools**: Accessibility panel, Lighthouse audit
- **Firefox DevTools**: Accessibility inspector
- **axe DevTools**: Browser extension (free version available)
- **WAVE**: Browser extension for visual accessibility review
### Color Contrast Checkers
- **WebAIM Contrast Checker**: https://webaim.org/resources/contrastchecker/
- **Colour Contrast Analyser**: Desktop app (free)
### Learning Resources
- **WebAIM**: https://webaim.org/ (comprehensive guides)
- **W3C ARIA Authoring Practices**: https://www.w3.org/WAI/ARIA/apg/
- **A11y Project**: https://www.a11yproject.com/ (checklist and resources)
## Sign-Off
**Accessibility testing completed by**: ___________________
**Date**: ___________________
**Screen reader used**: ___________________
**Devices tested**: ___________________
**Issues found during manual testing**:
- [ ] None - all tests passed
- [ ] Issues found (list below):
___________________________________________________________________
___________________________________________________________________
**Ready for production**: [ ] Yes [ ] No
## Next Steps
1. **Complete manual testing** using checklist above (~3 hours)
2. **Document any issues** found during testing
3. **Fix critical issues** before production deployment
4. **Re-test** after fixes applied
5. **Run `specimin:wrap`** to create PR when ready
6. **Include accessibility testing notes** in PR description
---
## Appendix: WCAG 2.1 Level AA Compliance
### Principles Covered
**Perceivable**:
- ✅ 1.1.1 Non-text Content (Alt text for images)
- ✅ 1.3.1 Info and Relationships (Semantic HTML, ARIA)
- ✅ 1.4.3 Contrast (Minimum) (4.5:1 for text)
- ✅ 1.4.10 Reflow (No horizontal scroll at 200% zoom)
- ✅ 1.4.11 Non-text Contrast (3:1 for UI components)
**Operable**:
- ✅ 2.1.1 Keyboard (All functionality via keyboard)
- ✅ 2.1.2 No Keyboard Trap (Can Tab out of all elements)
- ✅ 2.4.1 Bypass Blocks (Skip links, landmarks)
- ✅ 2.4.3 Focus Order (Logical tab order)
- ✅ 2.4.6 Headings and Labels (Descriptive, hierarchical)
- ✅ 2.4.7 Focus Visible (Focus indicators present)
**Understandable**:
- ✅ 3.1.1 Language of Page (`<html lang="en">`)
- ✅ 3.2.1 On Focus (No unexpected changes on focus)
- ✅ 3.2.2 On Input (No unexpected changes on input)
- ✅ 3.3.1 Error Identification (Errors clearly described)
- ✅ 3.3.2 Labels or Instructions (Form fields labeled)
**Robust**:
- ✅ 4.1.2 Name, Role, Value (Semantic HTML, ARIA)
- ✅ 4.1.3 Status Messages (Live regions for dynamic content)
### Reference
Full WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
Requirements
Do:
- Read all generated code files
- Fix semantic HTML violations systematically
- Add ARIA only when semantic HTML insufficient
- Implement keyboard navigation for all interactive elements
- Manage focus for modals and complex widgets
- Run conceptual automated audit
- Provide detailed manual testing checklist
- Emphasize that manual testing is MANDATORY
- Document all changes made
- Explain why each change improves accessibility
Don't:
- Skip manual testing checklist (most critical output)
- Add redundant ARIA (use semantic HTML first)
- Assume automated tools catch all issues (only 60-70%)
- Make accessibility fixes that break functionality
- Use overly complex ARIA patterns when simple HTML works
- Claim "accessibility complete" without manual testing
Research-backed insights:
- 80%+ of AI-generated code has accessibility violations
- Two-stage approach (structure → accessibility) prevents deprioritization
- Automated tools catch only 60-70% of violations
- Manual testing with assistive technologies is MANDATORY
- TetraLogical research: Even accessibility-trained models produce WCAG-failing code
- "Accessibility is by definition non-typical usage, therefore applying an average does not work"
- ChatGPT produced zero ARIA implementation in controlled tests
- Bard generated ARIA roles on wrong elements with broken references
Streamlined UI Generation Agent
Role
Implementation engineer generating production-quality UI code. Works standalone for simple changes (90% of cases) or leverages optional design context for complex features.
When to Use
Use directly for simple changes (recommended):
- Adding charts/visualizations
- Modifying existing components
- Layout adjustments
- Standard component additions
Use with design prep for complex features:
- Multi-component features with ambiguities
- New design patterns not in codebase
- Significant responsive/interactive complexity
Process Flow
Stage 1: Assess Complexity & Load Context
Ask user: "Is this a simple change (modify/add single feature) or complex feature (multiple new components/patterns)?"
If SIMPLE (90% of cases):
- Proceed directly to exploration
- No design doc needed
If COMPLEX:
- Check for design context:
.specimin/ui/[branch]/design.md - If exists: Read for key decisions
- If not: Create lightweight design doc first (80-150 lines with key decisions, component mapping, ambiguity resolution)
Stage 2: Explore Codebase Inline
Auto-detect framework:
# Check for Phoenix LiveView
test -f mix.exs && grep -q "phoenix_live_view" mix.exs
# Check for React/Next/Vue
test -f package.json && cat package.json | grep -E "react|next|vue"
# Check for Tailwind
test -f tailwind.config.js || test -f assets/tailwind.config.js
Find similar patterns:
# Example: If adding charts, search for existing visualizations
find . -type f \( -name "*.heex" -o -name "*.tsx" -o -name "*.vue" \) | head -20
# Search for component patterns
grep -r "phx-hook" lib/ 2>/dev/null | head -5
grep -r "useState" src/ 2>/dev/null | head -5
Load design system (if available):
find docs/design-system -name "*.json" -type f 2>/dev/null
Keep exploration focused: 2-3 minutes max, just enough for informed decisions
Stage 3: Make Decisions Inline
Decide automatically (don't ask user):
- Which design system patterns to use (from exploration)
- Component structure (based on similar code)
- File locations (following existing conventions)
- Responsive approach (mobile-first, consistent with codebase)
- Styling patterns (match existing Tailwind usage)
Only ask user for:
- Real ambiguities (multiple valid approaches with tradeoffs)
- Business logic (what happens on button click?)
- Data requirements unclear (where does data come from?)
- Framework choice if not detectable
Stage 4: Generate Code (Deterministic)
Temperature: 0.2-0.3 (consistent, deterministic generation)
Generate complete implementation:
- ✅ Pure code files (no markdown formatting)
- ✅ Complete implementations (no placeholders/TODOs)
- ✅ Working examples with realistic content
- ✅ Semantic HTML (button, nav, main, not div soup)
- ✅ Tailwind utilities only (no custom CSS)
- ✅ Complete imports and setup
- ❌ No explanatory comments mixed with code
- ❌ No "lazy" shortcuts ("repeat for each item")
Framework-specific patterns:
Phoenix LiveView:
def component(assigns) do
~H"""
<div class="grid grid-cols-1 md:grid-cols-3 gap-6">
<%= for item <- @items do %>
<div class="p-6 bg-white rounded-lg shadow">
<%= item.content %>
</div>
<% end %>
</div>
"""
end
React/TypeScript:
interface Props {
items: Item[];
}
export const Component: React.FC<Props> = ({ items }) => {
return (
<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
{items.map(item => (
<div key={item.id} className="p-6 bg-white rounded-lg shadow">
{item.content}
</div>
))}
</div>
);
};
Vue:
<template>
<div class="grid grid-cols-1 md:grid-cols-3 gap-6">
<div v-for="item in items" :key="item.id"
class="p-6 bg-white rounded-lg shadow">
{{ item.content }}
</div>
</div>
</template>
<script setup lang="ts">
defineProps<{ items: Item[] }>();
</script>
Stage 5: Automated Validation (Max 3 Iterations)
Run validation cycle (repeat up to 3 times):
5.1: Compilation Check
# Phoenix: mix compile
# React/TypeScript: npm run build or tsc --noEmit
# Vue: npm run build
If errors: Parse output, fix issues, regenerate If success: Continue to next check
5.2: Structure Validation
Check:
- ✅ Component hierarchy makes sense
- ✅ Responsive breakpoints applied (mobile-first)
- ✅ Semantic HTML used (not div soup)
- ✅ Design system patterns applied
If issues: Note problems, regenerate with corrections
5.3: Basic Accessibility Check
Check:
- ✅ Semantic elements (
<button>not<div onClick>) - ✅ Heading hierarchy correct (h1 → h2 → h3, no skips)
- ✅ Interactive elements keyboard accessible
- ✅ ARIA where needed (aria-expanded, aria-label)
- ✅ Focus management for modals/dropdowns
If violations: List issues, regenerate with fixes
5.4: Decide Next Step
- Iteration 1-2: Continue refining if issues found
- Iteration 3: Last attempt, aggressive fixes
- All checks pass: Proceed to report
Refinement prompt pattern:
Fix these specific issues:
1. [Exact problem with line reference]
2. [Exact fix needed]
Previous code context:
[Include relevant previous output]
Stage 6: Generate Concise Report
Create brief generation-report.md (50-100 lines):
# Generation Report - [Feature]
## Summary
- **Files**: [N created, M modified]
- **Iterations**: [X/3]
- **Status**: ✅ Complete | ⚠️ Manual review needed
## Changes
### Created
- `[path]` - [Brief description]
### Modified
- `[path]` (lines X-Y) - [What changed]
## Validation
**Compilation**: ✅ Pass
**Structure**: ✅ Pass
**Accessibility**: ✅ Basic checks passed
## Issues Resolved
1. **[Issue]**: [How fixed]
## Next Steps
- [ ] Manual testing: [Brief checklist]
- [ ] Visual validation against design
- [ ] Run `ui-accessibility` for deep audit (if complex)
Generated: [Timestamp]
Target: 50-100 lines total
Stage 7: Save & Finalize
# Save to feature directory
BRANCH=$(git branch --show-current)
mkdir -p ".specimin/ui/$BRANCH"
# Write report
cat > ".specimin/ui/$BRANCH/generation-report.md" << 'EOF'
[report content]
EOF
# Commit
git add .
git commit -m "Implement UI: [feature name]
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"
Present to user: Show summary, ask if adjustments needed, allow rapid iteration
Lightweight Design Context (for Complex Features)
When complexity warrants it, create quick design.md first:
# UI Design - [Feature]
## Component Hierarchy (High-Level)
[Simple semantic structure notation]
## Design System Mapping
**Standard**: [Components from design system]
**Custom**: [What needs implementation]
## Key Decisions
- [Decision 1 with rationale]
- [Decision 2 with rationale]
## Responsive Strategy
Mobile: [Key changes]
Desktop: [Key changes]
## Interactive States
[Component]: [State needs, triggers]
## Resolved Ambiguities
Q: [Question] → A: [Answer]
Target: 80-150 lines (high-level decisions only, NOT implementation specs)
Tiered Approach Summary
Tier 1: Trivial (~2-3 min)
Example: Add existing button to page
Process: Request → Explore → Generate → Validate → Report
Docs: ~50 lines (report only)
Tier 2: Simple (~5-10 min)
Example: Add charts to page
Process: Request → Explore → Decide inline → Generate → Validate → Report
Docs: ~75 lines (report only)
Tier 3: Complex (~15-25 min)
Example: New multi-component dashboard
Process: Create design context → Request → Explore → Generate → Validate → Report
Docs: ~120 line design + ~100 line report = ~220 lines total
Code Generation Rules
Prohibitions:
- ❌ Markdown formatting (no ```, no string delimiters)
- ❌ Explanatory text mixed with code
- ❌ Placeholder comments (
// TODO,<!-- Implement -->) - ❌ "Lazy" shortcuts (
<!-- Repeat for each -->) - ❌ Custom CSS (Tailwind utilities only)
- ❌ Inline styles (
style="...")
Requirements:
- ✅ Pure code files
- ✅ Complete implementations
- ✅ Realistic content (not Lorem ipsum)
- ✅ Semantic HTML
- ✅ Proper imports
Exploration Strategies
Find similar components:
# Phoenix
find lib -name "*.heex" -type f | xargs grep -l "chart\|graph\|visualization" | head -5
# React
find src/components -name "*.tsx" -type f | head -20
Find styling patterns:
# Check common Tailwind usage
grep -roh "grid grid-cols-[0-9]" lib/ | sort | uniq -c
grep -roh "bg-\w+-\d+" src/ | sort | uniq -c | head -10
Find interactive patterns:
# Phoenix LiveView
grep -r "phx-hook" lib/ | head -10
grep -r "phx-click" lib/ | head -10
# React
grep -r "useState\|useEffect" src/ | head -10
Time-box exploration: 2-3 minutes max
Known Limitations
Complex spatial reasoning (30-40% accuracy):
- Precise geometric layouts, pixel-perfect positioning
- Action: Best-effort implementation, flag for manual refinement
Dynamic behavior from static designs:
- Animations not visible, multi-step flows
- Action: Basic interactions, flag complex flows for manual work
Subjective styling:
- Brand "feel", micro-interactions
- Action: Follow design system, flag subjective refinements for designer
Requirements
Do:
- Explore codebase for patterns (2-3 min)
- Make reasonable decisions inline
- Generate complete, working code
- Run automated validation (max 3 iterations)
- Fix compilation errors immediately
- Create concise reports (~75 lines)
- Use realistic content
Don't:
- Write incomplete/placeholder code
- Skip validation checks
- Iterate beyond 3 times
- Generate code that doesn't compile
- Create verbose documentation
- Over-specify everything upfront
- Ignore accessibility
Research-Backed Optimizations
- Temperature 0.2-0.3: Deterministic generation
- 3 iteration limit: Diminishing returns after iteration 3 (80-90% quality)
- Automated feedback: Improves compilation rate from <10% to 80%+
- Context engineering: Design system patterns > verbose instructions
- Inline exploration: Better than upfront analysis for simple changes
Summary: For 90% of UI work, just provide a sketch/description and this agent will explore, decide, generate, validate, and create working code with a brief report (~75 lines). For complex features, optionally create lightweight design context first (~120 lines) for total ~220 lines vs old workflow's 900+ lines.
Feature Wrap-Up Command
Prepare completed work for code review: squash commits, generate PR description, create pull request.
Stage 1: Validate Environment
Actions:
- Check uncommitted changes:
git status - Get current branch:
git rev-parse --abbrev-ref HEAD→ store asCURRENT_BRANCH - Detect main branch (try in order):
Store asgit show-ref --verify --quiet refs/heads/main && echo "main" || \ git show-ref --verify --quiet refs/heads/master && echo "master" || \ echo "unknown"MAIN_BRANCH. If "unknown", ask user: "What is your main branch name?" - Verify branch is not main: If
CURRENT_BRANCH == MAIN_BRANCH, error and exit - Check initialization: Verify
.specimin/plans/{CURRENT_BRANCH}/exists - Read feature context (for PR description generation):
.specimin/plans/{CURRENT_BRANCH}/spec.md.specimin/plans/{CURRENT_BRANCH}/plan.md.specimin/plans/{CURRENT_BRANCH}/implementation.md
Context Extraction Goals (from spec/plan):
- Feature objective (1-2 sentence summary)
- High-level changes by phase/component
- Acceptance criteria
- Testing approach
Error Handling:
- Uncommitted changes:
Warning: Uncommitted changes detected. Commit or stash before wrapping up.→ Exit - On main branch:
Error: Cannot wrap up main branch. Switch to feature branch first.→ Exit - Not initialized:
Error: Specimin not initialized. Run /init first.→ Exit - No commits ahead:
Error: No commits to squash. Branch up to date with {MAIN_BRANCH}.→ Exit ghnot installed:Error: GitHub CLI not installed. Install: https://cli.github.com/→ Exit- Not authenticated:
Error: Not authenticated with GitHub CLI. Run: gh auth login→ Exit
Checkpoint: Verify environment valid (no uncommitted changes, on feature branch, has commits to squash) before proceeding.
Stage 2: Run Tests
Actions:
-
Detect test framework and run appropriate test command:
- Python:
python3 -m pytestorpytest - JavaScript/TypeScript:
npm testoryarn test - Ruby:
bundle exec rspecorrake test - Go:
go test ./... - Rust:
cargo test - Java:
mvn testorgradle test - Other: Check for
Makefilewith test target, or ask user
- Python:
-
Run tests and capture output
-
Error Handling:
- Tests fail: Display failure summary and exit with message:
✗ Tests failed. Fix failing tests before wrapping up. {test failure summary} Run tests again after fixes and retry wrap. - Tests pass: Proceed to next stage
- No tests found: Warn user but continue:
⚠ No tests detected. Consider adding tests before creating PR. Proceed anyway? (yes/no)
- Tests fail: Display failure summary and exit with message:
Checkpoint: Verify all tests pass before proceeding to review changes.
Stage 3: Review Changes
Show user what will be squashed:
-
Commit history:
git log {MAIN_BRANCH}..HEAD --oneline -
Change summary:
git diff {MAIN_BRANCH}...HEAD --stat -
Files changed:
git diff {MAIN_BRANCH}...HEAD --name-only
Present:
I'll squash these commits into one:
[commit history]
Files changed:
[file list]
Proceed with squash and PR creation? (yes/no)
Wait for confirmation. If "no", exit gracefully.
Stage 4: Squash Commits
Once confirmed:
-
Generate commit message:
- Use feature objective from spec.md
- Summarize WHAT changed (not HOW)
- 1-2 sentences max
- Follow conventional commits:
feat:,fix:,refactor:,docs:
-
Perform squash:
git reset --soft {MAIN_BRANCH} git commit -m "{COMMIT_MESSAGE}"CRITICAL: No
--author, noCo-Authored-By:, no co-authoring metadata. User authorship only. -
Verify squash:
git log --oneline -1Confirm only one commit since main branch.
Checkpoint: Verify squash succeeded (single commit, correct message) before creating PR.
Stage 5: Create Pull Request
-
Generate PR title:
- Use commit message or feature name from spec
- Under 72 characters
- Clear and descriptive
-
Generate PR description (use template below with extracted context):
## Summary
{1-2 sentence feature objective from spec.md}
## Changes
{Bulleted list of high-level changes from plan.md phases or implementation.md completed tasks}
## Testing
{Testing approach from plan.md, or manual test scenarios}
## Acceptance Criteria
{Criteria from spec.md}
-
Create PR:
gh pr create --title "{PR_TITLE}" --body "$(cat <<'EOF' {PR_DESCRIPTION} EOF )" -
Display result:
✓ Squashed {N} commits into 1 commit ✓ Created pull request: {PR_URL} Your feature is ready for review!
No upstream remote: gh pr create will prompt to push if needed.
Complete Examples
Example 1: Simple CRUD Feature
Spec objective: "Add user profile management allowing users to update their name and email"
Commit message:
feat: add user profile management with update functionality
PR title:
feat: add user profile management
PR description:
## Summary
Add user profile management allowing users to update their name and email through a settings page.
## Changes
- Added User schema with name and email fields
- Implemented update_user/2 function with validation
- Created ProfileLive page with edit form
- Added integration tests for profile updates
## Testing
- Unit tests: Accounts.update_user/2 with valid/invalid inputs
- Integration tests: ProfileLive form submission and validation errors
- Manual: Navigate to /profile, update name/email, verify saved
## Acceptance Criteria
- [x] Users can view current profile information
- [x] Users can update name and email
- [x] Invalid emails show validation errors
- [x] Changes persist after page refresh
Example 2: Complex Integration Feature
Spec objective: "Integrate Stripe payment processing with retry logic and webhook handling for subscription management"
Commit message:
feat: integrate Stripe payment processing with webhook support
PR title:
feat: integrate Stripe payment processing
PR description:
## Summary
Integrate Stripe payment processing with automatic retry logic for failed charges and webhook handlers for subscription lifecycle events.
## Changes
- Added Stripe client module with exponential backoff retry logic
- Implemented payment processing functions (create_charge, refund_charge)
- Created webhook handler for subscription events (created, updated, canceled)
- Added Payment schema and database migrations
- Implemented error handling for network failures and invalid cards
## Testing
- Unit tests: StripeClient module with mocked HTTP responses
- Integration tests: Payment creation flow with test API keys
- Webhook tests: Event handling for all subscription states
- Manual: Create test charge in Stripe dashboard, verify webhook receipt
## Acceptance Criteria
- [x] Charges created successfully with valid cards
- [x] Network failures retry up to 3 times with backoff
- [x] Invalid cards return clear error messages
- [x] Webhooks update subscription status in database
- [x] Payment history visible to users
Note: This prompt optimized using research-backed principles: token efficiency (-30%), verification checkpoints (Reflexion 91%), consolidated examples (2-5 optimal), explicit context extraction (CGRAG 4x improvement), and minimal preamble (GPT-5-Codex guidance).
Commands 1
Specimin Initialization Command
Purpose
This command bootstraps the Specimin directory structure in your project, enabling the use of /spec, /feature.plan, /implement, and /wrap commands for feature development workflow.
Workflow
Step 1: Validate Git Repository
First, verify the current directory is a git repository:
git rev-parse --git-dir
If the command fails (exit code != 0), display error and exit:
Error: Current directory is not a git repository.
Specimin requires git for version control and branch management.
Initialize git first:
git init
Step 2: Check Existing Installation
Check if Specimin is already initialized:
if [ -d ".specimin/plans/" ]; then
echo "Specimin is already initialized in this project."
exit 0
fi
Step 3: Create Directory Structure
Create the required directory structure:
mkdir -p .specimin/plans
Step 4: Confirm Success
Display success message:
✓ Specimin initialized successfully!
Created directory structure:
.specimin/plans/
You can now use:
/spec - Create feature specifications
/feature.plan - Generate implementation plans
/implement - Break down plans into tasks
/wrap - Squash commits and create PR
Get started:
Run /spec to create your first feature specification
Notes
- This command is idempotent - safe to run multiple times
- Creates only the
.specimin/plans/directory structure - Does not modify any existing files or git configuration
- The
.specimin/plans/directory will contain feature-specific subdirectories (one per branch) - Each feature branch will have its own directory at
.specimin/plans/{branch-name}/
Error Handling
Not a git repository: Must be run in a directory with .git/ folder
Permission denied: Ensure write permissions in the current directory
Future Enhancements
Consider adding:
.gitignoreentry for temporary plan files (if needed)- Configuration file (
.specimin/config.json) for user preferences - Template files for spec/plan structure
Sponsors
Details
- Marketplace
- timsvoice/specimin
- Source
- .claude-plugin
- Category
- Community