intent-start

What this skill does

# Intent Start

You are helping the user start a new intent using spec-driven development.

## Workflow

1. Ask the user: "What are you working on?" (brief description)
2. Ask if there's a Linear issue ID associated with this work (optional)
   - Example: "Do you have a Linear issue ID for this? (e.g., ABC-123, or press Enter to skip)"
3. Based on their answer, suggest a folder name in format:
   - **With Linear ID:** `YYYY-MM-DD-{repository-name}-{linear-id-lowercase}-{intent-description}`
   - **Without Linear ID:** `YYYY-MM-DD-{repository-name}-{intent-description}`
   - Get repository name from: `basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $(pwd)`
   - Linear ID should be converted to lowercase (e.g., `ABC-123` → `abc-123`)
   - Format examples:
     - With Linear ID: `2026-01-20-ai-code-skills-abc-123-add-dark-mode`
     - Without Linear ID: `2026-01-20-ai-code-skills-add-dark-mode`
4. Ask these questions to build the spec:
   - "What problem does this solve?"
   - "What's the proposed solution?"
   - "What are the key requirements?" (list 3-5 items)
   - "What are the acceptance criteria?" (how do we know it's done?)
   - "What's the implementation plan?" (break down into 3-7 concrete steps)

5. **Explore the codebase** to identify relevant code:
   - Search for files related to the feature/bug being worked on
   - Identify key entry points, functions, or components that will be modified
   - Find related tests or documentation
   - Note any dependencies or connected modules

6. Create the folder structure:
   ```
   {CLAUDE_INTENTS_FOLDER}/in-progress/YYYY-MM-DD-{repository-name}[-{linear-id-lowercase}]-{intent-description}/
   ├── spec.md
   └── notes.md
   ```
   - Get base path from: `echo "${CLAUDE_INTENTS_FOLDER:-$HOME/.claude-intents}"`
   - Include Linear ID (lowercase) after repository name if provided

7. Write **spec.md** with this structure:
   ```markdown
   # [Intent Title]

   **Date Started:** YYYY-MM-DD
   **Status:** In Progress
   **Linear Issue:** [ABC-123](https://linear.app/team/issue/ABC-123) <!-- Include if Linear ID provided -->

   ## Problem
   [Problem statement]

   ## Solution
   [Proposed solution]

   ## Requirements
   - [ ] Requirement 1
   - [ ] Requirement 2
   - [ ] Requirement 3

   ## Acceptance Criteria
   - [ ] Criteria 1
   - [ ] Criteria 2

   ## Implementation Plan
   1. [Step 1]
   2. [Step 2]
   3. [Step 3]
   4. [Step 4]
   5. [Step 5]

   ## Relevant Code

   ### Key Files
   | File | Purpose |
   |------|---------|
   | `path/to/file.ts:42` | Brief description of relevance |
   | `path/to/another.ts:15-30` | Brief description of relevance |

   ### Code Snippets
   <!-- Include key code snippets that are central to this intent -->

   **[filename.ts:line]** - Description
   ```typescript
   // Relevant code snippet
   ```

   ## Architecture (Optional)
   <!-- Include Mermaid diagrams when they help visualize: -->
   <!-- - Data flow between components -->
   <!-- - State transitions -->
   <!-- - Sequence of operations -->
   <!-- - System architecture changes -->

   ```mermaid
   flowchart TD
       A[Component A] --> B[Component B]
       B --> C[Component C]
   ```

   ## Notes
   [Any additional context]
   ```

8. Write **notes.md** with:
   ```markdown
   # Development Notes

   ## YYYY-MM-DD - Intent Started
   - Created spec
   - [Any initial notes from the conversation]
   ```

9. Create a todo list using TodoWrite tool:
   - Convert each step from the implementation plan into a todo item
   - Set all items to "pending" status
   - Use the imperative form for content (e.g., "Implement feature X")
   - Use the present continuous form for activeForm (e.g., "Implementing feature X")
   - This helps track progress throughout the intent lifecycle

10. Confirm intent creation and show the path

## Important Notes

- **Base path:** Use the `CLAUDE_INTENTS_FOLDER` environment variable. If not set, default to `~/.claude-intents`
- To get base path, run: `echo "${CLAUDE_INTENTS_FOLDER:-$HOME/.claude-intents}"`
- **Repository name:** Get from git using: `basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $(pwd)`
- If not in a git repo, use the current folder name as repository name
- **Linear ID (optional):** When provided, include lowercase Linear ID after repository name
  - Convert to lowercase: `ABC-123` → `abc-123`
  - Include in spec.md with link: `**Linear Issue:** [ABC-123](https://linear.app/team/issue/ABC-123)`
  - Useful for branch naming: `git checkout -b abc-123-intent-description`
- Use today's date for folder name
- Keep folder name lowercase with hyphens
- Create `{CLAUDE_INTENTS_FOLDER}/in-progress/` directory if it doesn't exist
- Since intents are stored outside the repo (in `~/.claude-intents` by default), no gitignore changes are needed unless using a custom `CLAUDE_INTENTS_FOLDER` inside a repo

## Code Context Guidelines

When documenting relevant code:

- **Use relative paths** from the repository root (e.g., `src/components/Button.tsx:42`)
- **Include line numbers** for specific functions or sections (e.g., `:42` or `:15-30` for ranges)
- **Keep snippets focused** - only include the most relevant 5-15 lines, not entire files
- **Prioritize entry points** - document where the change begins (handlers, API endpoints, etc.)

## Mermaid Chart Guidelines

Include Mermaid diagrams when they help visualize:

- **Flowcharts** - for complex logic or decision trees
- **Sequence diagrams** - for multi-component interactions or API flows
- **State diagrams** - for state machine changes
- **Entity relationships** - for data model changes

Skip diagrams for:

- Simple, linear implementations
- Single-file changes
- Bug fixes with obvious flow

Supported diagram types:

```text
flowchart TD    - Top-down flowchart
sequenceDiagram - Interaction between components
stateDiagram-v2 - State transitions
erDiagram       - Entity relationships
classDiagram    - Class structures
```