Create Plan

Create Implementation Plan

Generate comprehensive implementation plans that provide strategic guidance without making actual code changes.

When to Use

• User explicitly requests a plan, roadmap, or implementation strategy
• Complex tasks requiring structured breakdown before implementation
• Need for risk assessment and alternative approach analysis
• Pre-implementation analysis of architectural decisions

Planning Process

1. Initial Assessment

Research the codebase to understand:

• Project structure and organization
• Relevant files and components - read thoroughly to understand complete flows
• Existing patterns and conventions
• Potential challenges and risks
• Data flows from entry points to final usage

Use search, sem_search, and read tools to examine the codebase. Use sage if deeper research is required for the use-case. Explicitly cite sources using filepath:line format in your plan.

2. Create Strategic Plan

Generate a Markdown plan file in plans/ directory with naming: plans/{YYYY-MM-DD}-{task-name}-v{N}.md

Example: plans/2025-11-24-add-auth-v1.md

3. Validate Plan

MANDATORY: Run the validation script to ensure the plan meets all requirements:

./.forge/skills/create-plan/validate-plan.sh plans/{YYYY-MM-DD}-{task-name}-v{N}.md

Fix any errors or warnings and re-validate until the plan passes all checks.

4. Plan Structure

# [Task Name]

## Objective

[Clear statement of goal and expected outcomes]

## Implementation Plan

- [ ] 1. [First task with detailed description and rationale]
- [ ] 2. [Second task with detailed description and rationale]
- [ ] 3. [Third task with detailed description and rationale]

## Verification Criteria

- [Criterion 1: Specific, measurable outcome]
- [Criterion 2: Specific, measurable outcome]

## Potential Risks and Mitigations

1. **[Risk Description]**
   Mitigation: [Specific mitigation strategy]

2. **[Risk Description]**
   Mitigation: [Specific mitigation strategy]

## Alternative Approaches

1. [Alternative 1]: [Brief description and trade-offs]
2. [Alternative 2]: [Brief description and trade-offs]

Critical Requirements

• ALWAYS validate the plan using ./.forge/skills/create-plan/validate-plan.sh after creation
• ALWAYS use checkbox format (- [ ]) for ALL implementation tasks
• NEVER use numbered lists or plain bullet points in Implementation Plan section
• NEVER write code, code snippets, or code examples in the plan
• Write comprehensive tasks including what, why, affected files, and integration points
• Use filepath:line format for file references (e.g., crates/forge_repo/src/provider.rs:45)
• Include clear rationale for each task
• Provide specific, measurable verification criteria
• Document assumptions made for ambiguous requirements
• Focus on strategic "what" and "why", not tactical "how"
• Describe what needs to be done using natural language, not code

Best Practices

• Make reasonable assumptions when requirements are ambiguous
• Use codebase patterns to infer best practices
• Provide multiple solution paths for complex challenges
• Balance thoroughness with actionability
• Create plans that can be executed step-by-step by implementation agents

Boundaries

This is a planning-only skill:

• ✅ Research codebase and analyze structure
• ✅ Create strategic plans and documentation
• ✅ Assess risks and propose alternatives
• ✅ Describe implementations using natural language
• ❌ Make actual code changes
• ❌ Modify files or create implementations
• ❌ Run tests or build commands
• ❌ Write code, code snippets, or code examples in plans

If user requests implementation work, suggest switching to an implementation agent.

Create Plan Skill

Tools and scripts for creating and validating implementation plans.

Files

• SKILL.md - Main skill instructions for AI agents
• validate-plan.sh - Validates a single plan file
• validate-all-plans.sh - Validates all plans in a directory

Validation Scripts

validate-plan.sh

Validates the structure and content of a single plan file.

Usage:

./.forge/skills/create-plan/validate-plan.sh plans/2025-11-27-example-v1.md

Checks:

• ✓ Filename follows convention: YYYY-MM-DD-task-name-vN.md
• Year is reasonable (2020 to current year + 1)
• Month is valid (01-12)
• Day is valid (01-31)
• Task name is meaningful (not generic like "test", "task", "temp")
• Task name length is reasonable (5-60 characters)
• Version number is reasonable (not > 50)
• No uppercase letters or underscores (use lowercase and hyphens only)
• ✓ File is in plans/ directory
• ✓ All required sections present:
• Main heading (# Title)
• ## Objective
• ## Implementation Plan
• ## Verification Criteria
• ## Potential Risks and Mitigations
• ## Alternative Approaches
• ✓ Implementation Plan uses checkbox format (- [ ])
• ✓ No numbered lists or plain bullets in Implementation Plan
• ✓ No code blocks ( ` ) in the plan
• ✓ No code snippets (detects suspicious patterns)
• ✓ No placeholder tasks (TODO, TBD, etc.)
• ✓ Task quality and density:
• Task descriptions are descriptive (≥ 20 characters recommended)
• Average task length is substantial (30-200 chars recommended)
• No generic/vague descriptions ("implement feature", "fix bug", etc.)
• No duplicate or highly similar tasks
• Consistent and sequential numbering if tasks are numbered
• ✓ Verification criteria have content
• ✓ Risks include mitigations
• ✓ Reasonable number of tasks (3-20)

Exit Codes:

• 0 - Validation passed
• 1 - Validation failed (errors found)

validate-all-plans.sh

Validates all plan files in a directory.

Usage:

# Validate all plans in default directory (plans/)
./.forge/skills/create-plan/validate-all-plans.sh

# Validate plans in custom directory
./.forge/skills/create-plan/validate-all-plans.sh path/to/plans

Exit Codes:

• 0 - All plans passed validation
• 1 - One or more plans failed validation

Integration

Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash
# Validate plans before committing

if git diff --cached --name-only | grep -q "^plans/.*\.md$"; then
    echo "Validating modified plans..."
    ./.forge/skills/create-plan/validate-all-plans.sh plans/
    exit $?
fi

CI/CD

Add to your CI pipeline:

- name: Validate Plans
  run: ./.forge/skills/create-plan/validate-all-plans.sh plans/

Example Valid Plan

See SKILL.md for the complete plan template structure.

Common Validation Errors

1. Invalid filename format: Must follow YYYY-MM-DD-task-name-vN.md pattern

• Use lowercase letters only
• Use hyphens (not underscores) to separate words
• Use valid date (month 01-12, day 01-31, year 2020+)
• Avoid generic names like "test", "task", "temp"

2. Missing checkboxes: Use - [ ] not 1. or - 3. Code blocks: Plans should use natural language, not code 4. Missing sections: All required sections must be present 5. Empty sections: Sections should have meaningful content 6. Poor task quality: Tasks should be descriptive and specific

• Avoid short descriptions like "Do this", "Fix that", "Update code"
• Avoid generic descriptions like "implement feature", "add functionality"
• Include rationale and context in task descriptions
• Aim for 30-150 characters per task description

Add User Authentication System

Objective

Implement a secure user authentication system with JWT-based token management, password hashing, and session handling. The system should support user registration, login, logout, and token refresh capabilities while maintaining security best practices.

Implementation Plan

• [ ] 1. Set up authentication dependencies and configuration
• Add JWT library (e.g., jsonwebtoken) and bcrypt for password hashing
• Configure environment variables for JWT secrets and token expiration
• Rationale: Establishes foundation for secure authentication
• Dependencies: None - this is the first step

• [ ] 2. Create user model and database schema
• Define User entity with fields: id, email, password_hash, created_at, updated_at
• Add unique constraint on email field
• Create database migration for users table
• Rationale: Provides data structure for storing user credentials
• Dependencies: Database connection must be configured

• [ ] 3. Implement password hashing service
• Create service to hash passwords using bcrypt with appropriate salt rounds
• Add password verification function
• Include unit tests for hashing and verification
• Rationale: Ensures passwords are never stored in plain text
• Dependencies: User model must exist

• [ ] 4. Build JWT token generation and validation
• Create service to generate JWT tokens with user claims
• Implement token verification and decoding logic
• Add refresh token functionality with longer expiration
• Rationale: Enables stateless authentication and session management
• Dependencies: User model and environment configuration

• [ ] 5. Create authentication endpoints
• POST /auth/register - User registration with email/password
• POST /auth/login - User login returning access and refresh tokens
• POST /auth/logout - Invalidate user session
• POST /auth/refresh - Generate new access token from refresh token
• Rationale: Provides API interface for authentication operations
• Dependencies: All services from previous steps

• [ ] 6. Implement authentication middleware
• Create middleware to validate JWT tokens on protected routes
• Extract user information from valid tokens
• Return 401 for invalid or expired tokens
• Rationale: Protects routes requiring authentication
• Dependencies: JWT validation service

• [ ] 7. Add rate limiting for authentication endpoints
• Implement rate limiting on login and registration endpoints
• Configure appropriate limits (e.g., 5 attempts per 15 minutes)
• Rationale: Prevents brute force attacks
• Dependencies: Authentication endpoints must exist

• [ ] 8. Write integration tests for authentication flow
• Test complete registration → login → access protected route flow
• Test token refresh mechanism
• Test error cases (invalid credentials, expired tokens)
• Rationale: Ensures entire authentication system works correctly
• Dependencies: All implementation steps complete

Verification Criteria

• User can successfully register with valid email and password
• User can login and receive valid JWT tokens
• Protected routes return 401 for unauthenticated requests
• Protected routes allow access with valid JWT token
• Tokens expire after configured duration
• Refresh tokens can generate new access tokens
• Passwords are hashed and never stored in plain text
• Rate limiting prevents excessive authentication attempts
• All unit and integration tests pass
• Security audit shows no critical vulnerabilities

Potential Risks and Mitigations

1. Token Secret Exposure

• Impact: If JWT secret is exposed, attackers can forge valid tokens
• Likelihood: Medium
• Mitigation: Store secrets in environment variables, never commit to repository, rotate secrets periodically
• Contingency: Implement secret rotation mechanism and token revocation list

2. Weak Password Policy

• Impact: Users choose weak passwords that are easily compromised
• Likelihood: High
• Mitigation: Enforce minimum password requirements (length, complexity), implement password strength meter
• Contingency: Add option to require password reset for weak passwords

3. Session Hijacking

• Impact: Attacker steals valid token and impersonates user
• Likelihood: Medium
• Mitigation: Use HTTPS only, implement short token expiration, add IP address validation
• Contingency: Implement token revocation and force logout capability

4. Brute Force Attacks

• Impact: Attacker attempts many password combinations to gain access
• Likelihood: High
• Mitigation: Implement rate limiting, add CAPTCHA after failed attempts, temporary account lockout
• Contingency: Monitor failed login attempts and alert on suspicious patterns

Alternative Approaches

1. Session-Based Authentication

• Description: Use traditional server-side sessions with cookies instead of JWT
• Pros: Easier to invalidate sessions, better for server-rendered applications, no token size limitations
• Cons: Requires session storage (Redis/database), harder to scale horizontally, not suitable for APIs consumed by multiple clients
• Recommendation: Not chosen - JWT better suits stateless API architecture

2. OAuth 2.0 / Third-Party Authentication

• Description: Use OAuth providers (Google, GitHub) for authentication instead of custom system
• Pros: No password management, better security through established providers, easier for users
• Cons: Dependency on external services, requires API keys and setup, limited control over authentication flow
• Recommendation: Consider as future enhancement alongside custom authentication

3. Passwordless Authentication

• Description: Use magic links or OTP sent via email/SMS instead of passwords
• Pros: No password management, simpler user experience, eliminates weak password risk
• Cons: Requires reliable email/SMS delivery, slower authentication flow, potential cost for SMS
• Recommendation: Consider as alternative authentication method in future iteration

Assumptions

• Application already has database connection configured
• HTTPS/TLS is configured at infrastructure level
• Email service is available for potential password reset features
• Frontend application exists to consume authentication endpoints
• Environment variable management system is in place

Dependencies

• Database system (PostgreSQL, MySQL, or similar)
• JWT library compatible with the programming language
• Password hashing library (bcrypt or argon2)
• HTTP server framework with middleware support
• Environment configuration system

Notes

• Consider implementing password reset functionality in a follow-up iteration
• May want to add two-factor authentication (2FA) as security enhancement
• Monitor token expiration times and adjust based on usage patterns
• Plan for token revocation strategy if needed for security incidents

[Task Name]

Objective

[Provide a clear, concise statement of what this plan aims to achieve. Include expected outcomes and success indicators. Be specific about the end goal.]

Implementation Plan

All tasks must use checkbox format for tracking:

• [ ] 1. [First major task]
• Detailed description of what needs to be done
• Rationale: Why this task is necessary
• Dependencies: What must be completed before this
• Key considerations: Important factors to keep in mind

• [ ] 2. [Second major task]
• Detailed description of what needs to be done
• Rationale: Why this task is necessary
• Dependencies: What must be completed before this
• Key considerations: Important factors to keep in mind

• [ ] 3. [Third major task]
• Detailed description of what needs to be done
• Rationale: Why this task is necessary
• Dependencies: What must be completed before this
• Key considerations: Important factors to keep in mind

[Continue with additional tasks as needed]

Verification Criteria

Define specific, measurable criteria to verify successful completion:

• [Criterion 1]: Specific test or check that confirms this aspect works
• [Criterion 2]: Measurable outcome that indicates success
• [Criterion 3]: Observable behavior that validates the implementation
• [Criterion 4]: Performance or quality metric that must be met

Potential Risks and Mitigations

Identify risks and provide concrete mitigation strategies:

1. [Risk Name/Description]

• Impact: [Describe the potential impact if this risk occurs]
• Likelihood: [High/Medium/Low]
• Mitigation: [Specific strategy to prevent or minimize this risk]
• Contingency: [Backup plan if mitigation fails]

2. [Risk Name/Description]

• Impact: [Describe the potential impact if this risk occurs]
• Likelihood: [High/Medium/Low]
• Mitigation: [Specific strategy to prevent or minimize this risk]
• Contingency: [Backup plan if mitigation fails]

[Continue with additional risks as needed]

Alternative Approaches

Document alternative solutions considered and their trade-offs:

1. [Alternative Approach 1]

• Description: [How this approach would work]
• Pros: [Advantages of this approach]
• Cons: [Disadvantages or limitations]
• Recommendation: [Why chosen or not chosen]

2. [Alternative Approach 2]

• Description: [How this approach would work]
• Pros: [Advantages of this approach]
• Cons: [Disadvantages or limitations]
• Recommendation: [Why chosen or not chosen]

[Continue with additional alternatives as needed]

Assumptions

Document any assumptions made during planning:

• [Assumption 1]: [Why this assumption was made]
• [Assumption 2]: [Why this assumption was made]
• [Assumption 3]: [Why this assumption was made]

Dependencies

List external dependencies or prerequisites:

• [Dependency 1]: [What is needed and why]
• [Dependency 2]: [What is needed and why]
• [Dependency 3]: [What is needed and why]

Notes

Additional context or considerations:

• [Note 1]
• [Note 2]
• [Note 3]