
aintentfirst
AI Intent First integration - ticket workflow for Claude Code
- version
- 1.0.0
Install
/plugin install aintentfirst@aintentfirst-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add yvocilon/aintentfirst-plugin.
Contents
Discovered from sourceCommands 4
/init - Connect Repository to AI Intent First
Connect the current repository to an AI Intent First project and configure MCP access.
Steps
1. Check MCP Configuration
Run this command to check if the MCP is already configured:
claude mcp get aintentfirst
- If it returns configuration, the MCP is set up - skip to step 3
- If it fails or returns nothing, proceed to step 2
2. Configure MCP Access
If MCP is not configured, ask the user for their API token:
To connect to AI Intent First, I need your API token.
Get one at: https://aintentfirst.com/settings/tokens
Please paste your token:
Once you have the token, run:
claude mcp add --transport http \
--header "Authorization: Bearer <TOKEN>" \
aintentfirst https://aintentfirst.com/api/mcp -s local
Replace <TOKEN> with the user's token. This configures the MCP for the local project scope.
3. Check Existing Project Mapping
Check if this repo is already connected to a project. First get the current directory:
pwd
Take the output (e.g., /Users/yvocilon/Repos/note-taker) and replace all / with %2F to get the encoded path.
Then check for existing config:
cat ~/.claude/projects/<ENCODED_PATH>/.aintentfirst.json 2>/dev/null
If a mapping exists, show the current connection and ask if they want to change it.
4. List Available Projects
Call the MCP tool to list projects:
mcp__aintentfirst__list_projects
Display the available projects to the user.
5. Select Project
Ask the user which project to connect to this repository.
If there's only one project, suggest it as the default.
6. Save Project Mapping
Create the config directory using the encoded path from step 3:
mkdir -p ~/.claude/projects/<ENCODED_PATH>
Then write the JSON file with this structure:
{
"projectId": "<selected-project-uuid>",
"projectName": "<selected-project-name>",
"connectedAt": "<ISO-8601-timestamp>"
}
Save to: ~/.claude/projects/<ENCODED_PATH>/.aintentfirst.json
7. Check for Existing Project Docs
Call the MCP tool to list existing documentation:
mcp__aintentfirst__list_project_docs with projectId
If docs already exist, skip to step 11 (Confirm).
8. Offer to Generate Docs
If no docs exist, ask the user:
No project documentation found.
I can analyze this codebase and generate functional documentation to help the LLM ask better clarifying questions on tickets.
This will create:
TERMINOLOGY.md- Project-specific terms and conceptsSCREENS.md- UI screens and pagesUSER_FLOWS.md- Key user journeysBUSINESS_RULES.md- Domain constraints and rulesGenerate documentation now?
- Yes - Analyze codebase and upload docs
- No - Skip for now (you can run
/sync-docslater)
If "No", skip to step 11 (Confirm).
9. Analyze Codebase
Use the Explore agent to analyze the codebase for functional aspects:
-
Terminology: Look for domain-specific terms in code comments, variable names, type definitions, and documentation files. Focus on business concepts, not technical terms.
-
Screens: Find React components that represent pages/screens. Look in routes, pages, or views directories. Note the purpose of each screen.
-
User Flows: Trace how users accomplish key tasks. Look at route structures, form submissions, and state transitions.
-
Business Rules: Find validation logic, permission checks, status transitions, and constraints in the code.
Focus on functional aspects visible to stakeholders, not technical implementation details. Skip:
- Tech stack details
- API endpoint implementations
- Database schema specifics
- Code patterns and architecture
10. Upload Documentation
For each doc type that has meaningful content, create a project document:
mcp__aintentfirst__create_project_doc with:
- projectId: <selected-project-uuid>
- name: "TERMINOLOGY.md" (or SCREENS.md, USER_FLOWS.md, BUSINESS_RULES.md)
- content: <generated markdown content>
Show progress as each doc is uploaded:
Uploading TERMINOLOGY.md... ✓
Uploading SCREENS.md... ✓
Uploading USER_FLOWS.md... ✓
Uploading BUSINESS_RULES.md... ✓
11. Confirm
Display confirmation:
Connected to AI Intent First project: <project-name>
You can now use:
/pick-ticket - Pick up a todo ticket and create a worktree
/resume-ticket - Resume work on the current ticket
/sync-docs - Update project documentation
If docs were generated, also show:
Project documentation uploaded:
- TERMINOLOGY.md
- SCREENS.md
- USER_FLOWS.md
- BUSINESS_RULES.md
The LLM will use these docs when asking clarifying questions on new tickets.
Notes
- The config is stored per-repo in
~/.claude/projects/<encoded-path>/ - The MCP scope is
localso it only applies to this project - Re-running
/initallows changing the connected project - Use
/sync-docsto update documentation after making changes to the codebase
/pick-ticket - Pick Up a Todo Ticket
Fetch a todo ticket from AI Intent First, create a git worktree, and enter plan mode to start implementing.
Steps
1. Load Project Configuration
Get the project mapping for the current repository. First, get the current directory and encode it:
pwd
Take the output (e.g., /Users/yvocilon/Repos/note-taker) and replace all / with %2F to get the encoded path (e.g., %2FUsers%2Fyvocilon%2FRepos%2Fnote-taker).
Then read the config file:
cat ~/.claude/projects/<ENCODED_PATH>/.aintentfirst.json
The file contains projectId, projectName, and connectedAt.
If the file doesn't exist, tell the user:
This repository isn't connected to an AI Intent First project. Run
/initfirst to set up the connection.
Then stop.
2. Fetch Todo Tickets
Call the MCP tool to list tickets:
mcp__aintentfirst__list_tickets with projectId and status: "todo"
If no tickets are in "todo" status, inform the user:
No todo tickets available. All caught up!
Then stop.
3. Show Tickets for Approval
For the first ticket, display:
- Title
- Brief description (first 100 chars or so)
Ask the user:
Pick up this ticket?
- Yes - Lock ticket and create worktree
- Skip - Show next ticket
- No - Stop
If "Skip", show the next ticket. Continue until user picks one or says "No".
4. Lock the Ticket
Once approved, call:
mcp__aintentfirst__get_ticket with ticketId
This auto-moves the ticket to "in_progress", locking it from other Claude instances.
Display the full ticket details including any project documentation.
5. Create Worktree (or use existing)
First check if the worktree already exists:
WORKTREE_PATH="../$(basename $(pwd))-worktrees/ticket-<short-id>"
test -d "$WORKTREE_PATH" && echo "exists" || echo "create"
If worktree doesn't exist: Run the worktree script:
~/.claude/scripts/worktree-new.sh "<ticket-id>"
The script will:
- Create a branch named
ticket/<short-id>(first 8 chars of UUID) - Create a worktree at
../<repo-name>-worktrees/ticket-<short-id>/ - Symlink
.envfrom main repo - Install dependencies (auto-detects pnpm/npm/yarn/bun)
Capture the WORKTREE_PATH from the script output.
If worktree already exists: Just use the existing path. Still continue with ALL remaining steps.
CRITICAL: Whether the worktree is new or existing, you MUST continue to Steps 5.5, 6, 7, and 8. Do NOT stop early just because the worktree exists.
5.5. Save Ticket Context to TICKET.md
Write the full ticket details to TICKET.md in the worktree root for the automated workflow:
# Ticket: <short-id>
## Title
<ticket title>
## Description
<full description from get_ticket response>
## Requirements
- <extract key requirements as bullet points from description and clarification>
## Constraints
- <extract constraints from clarification Q&A thread>
## Project Context
<include relevant project documentation returned by get_ticket>
Write this file to <worktree-path>/TICKET.md. This provides context for the automated planning step.
6. Change to Worktree Directory
Change your working directory to the worktree:
cd <worktree-path>
This ensures all subsequent git operations happen in the correct branch.
7. Display Task Summary
Show the ticket details you already retrieved in step 4:
✓ Worktree ready: <worktree-path>
✓ Branch: ticket/<short-id>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Ticket: <short-id>
Title: <ticket title>
Task: <summarize the main task in 2-3 sentences>
Key Requirements:
- <bullet points from description/clarification>
Constraints:
- <any important constraints from the clarification thread>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
8. Launch Automated Docker Sandbox
Launch a Docker sandbox with an automated prompt that will:
- Run
/workflows:planto create an implementation plan - Wait for user approval
- Implement, commit, push, and create a PR
Tell the user:
✓ Ready to launch automated workflow
A Docker sandbox will open with full access to the worktree. Claude will automatically:
- Plan the implementation using
/workflows:plan- Show you the plan for approval
- After your approval: implement, commit, push, and create a PR
Opening sandbox now...
Then run the open-worktree script which will launch the Docker sandbox:
~/.claude/plugins/repos/aintentfirst-plugin/scripts/open-worktree.sh "<worktree-path>"
The script opens a new terminal with the Docker sandbox pre-configured with the automated prompt.
Do NOT enter plan mode yourself - the Docker sandbox handles the entire workflow.
Notes
- Only call
get_ticketafter user approval - that's what locks the ticket - The worktree is created in
../<repo-name>-worktrees/ticket-<short-id>/ - All file paths should use the worktree path, not the main repo
- After plan approval, implement the feature in the worktree
/resume-ticket - Resume Work on Current Ticket
Automatically load ticket context when working in a ticket worktree.
When to Use
Run this when you start a new Claude session in a worktree created by /pick-ticket. It detects the ticket from your branch and loads all context.
Steps
1. Get Current Branch Name
git branch --show-current
Expect format: ticket/<short-id> (e.g., ticket/7ceb92bd)
2. Extract Ticket ID
Parse the short ID from the branch name (everything after ticket/).
If the branch doesn't match the ticket/* pattern:
This doesn't appear to be a ticket branch. Expected format:
ticket/<id>(e.g.,ticket/7ceb92bd)Use
/pick-ticketto start working on a new ticket.
Then stop.
3. Find Project Configuration
First, find the main repo path (this works correctly in worktrees):
git rev-parse --path-format=absolute --git-common-dir
Take the output (e.g., /Users/yvocilon/Repos/note-taker/.git) and remove the /.git suffix to get the main repo path.
Then encode the path by replacing all / with %2F and read the config:
cat ~/.claude/projects/<ENCODED_MAIN_REPO_PATH>/.aintentfirst.json
The file contains projectId, projectName, and connectedAt.
If no config exists, tell the user to run /init in the main repository.
4. Find Full Ticket ID
The branch has a short ID (first 8 chars), but MCP needs the full UUID.
Call:
mcp__aintentfirst__list_tickets with projectId and status: "in_progress"
Find the ticket whose ID starts with the short ID from the branch.
If no match found:
Could not find an in-progress ticket matching
<short-id>.The ticket may have been completed or moved to a different status.
5. Fetch Full Ticket Details
Call:
mcp__aintentfirst__get_ticket with ticketId (the full UUID)
This returns:
- Full ticket description
- Clarification Q&A thread
- Project documentation
6. Save or Update TICKET.md
Check if TICKET.md exists in the current directory:
test -f TICKET.md && echo "exists" || echo "missing"
If missing, write it using the ticket details from step 5:
# Ticket: <short-id>
## Title
<ticket title>
## Description
<full description from get_ticket response>
## Requirements
- <extract key requirements as bullet points from description and clarification>
## Constraints
- <extract constraints from clarification Q&A thread>
## Project Context
<include relevant project documentation returned by get_ticket>
This file is required for the automated workflow.
7. Display Task Summary and Prompt for Next Steps
Show a clear summary:
Resuming ticket: <short-id>
Title: <ticket title>
Status: in_progress
Task: <summarize the main task in 2-3 sentences>
Key Requirements:
- <bullet points from description/clarification>
Constraints:
- <any important constraints from the clarification thread>
TICKET.md: <"Found" or "Created">
Then ask the user what they want to do next:
How would you like to proceed?
- Plan - Run
/workflows:planto create/update the implementation plan- Work - Run
/workflows:workto continue implementing (if plan already approved)- Manual - Enter plan mode for manual implementation
If the user chooses "Plan", run /workflows:plan with @TICKET.md as context.
If the user chooses "Work", run /workflows:work to continue implementation.
If the user chooses "Manual", enter plan mode using the EnterPlanMode tool.
Example Output
Resuming ticket: 7ceb92bd
Title: Add polling to project dashboard
Status: in_progress
Task: Add periodic polling to the project dashboard so changes made
via MCP (new tickets, status updates) appear without manual refresh.
Key Requirements:
- Poll for ticket list changes every few seconds
- Detect: new tickets, status moves, tag changes, title edits
- Dashboard only (not ticket detail pages)
Constraints:
- No conflict resolution needed for simultaneous edits
- Polling interval of a few seconds is acceptable
Entering plan mode to design the implementation...
Notes
- Use this command when starting a new Claude session in a ticket worktree
- The short ID (8 chars) is matched against full UUIDs via
startsWith - Project config is found by looking at the main repo path, not the worktree
- After loading context, Claude automatically enters plan mode
/sync-docs - Sync Project Documentation
Update existing documentation and create any missing standard docs for the connected AI Intent First project.
When to Use
Run this after:
- Adding new features or screens
- Changing business rules or workflows
- Introducing new domain terminology
- Any significant codebase changes that affect functional behavior
Steps
1. Load Project Configuration
Get the project mapping for the current repository:
CONFIG_FILE=~/.claude/projects/$(echo "$PWD" | sed 's/\//%2F/g')/.aintentfirst.json
cat "$CONFIG_FILE" 2>/dev/null
If no config exists, tell the user:
This repository isn't connected to an AI Intent First project. Run
/initfirst to set up the connection.
Then stop.
2. List Existing Docs
Call the MCP tool to list current documentation:
mcp__aintentfirst__list_project_docs with projectId
Note which standard docs exist:
TERMINOLOGY.mdSCREENS.mdUSER_FLOWS.mdBUSINESS_RULES.md
3. Analyze Codebase
Use the Explore agent to analyze the codebase for functional aspects:
-
Terminology: Look for domain-specific terms in code comments, variable names, type definitions, and documentation files. Focus on business concepts, not technical terms.
-
Screens: Find React components that represent pages/screens. Look in routes, pages, or views directories. Note the purpose of each screen.
-
User Flows: Trace how users accomplish key tasks. Look at route structures, form submissions, and state transitions.
-
Business Rules: Find validation logic, permission checks, status transitions, and constraints in the code.
Focus on functional aspects visible to stakeholders, not technical implementation details. Skip:
- Tech stack details
- API endpoint implementations
- Database schema specifics
- Code patterns and architecture
4. Update Existing Docs
For each standard doc that already exists:
-
Get the current content:
mcp__aintentfirst__get_project_doc with projectId and docId -
Compare with freshly analyzed content
-
If there are meaningful changes, update:
mcp__aintentfirst__update_project_doc with: - projectId - docId - name: <same name> - content: <updated markdown content>
Show progress:
Checking TERMINOLOGY.md... updated
Checking SCREENS.md... no changes
Checking USER_FLOWS.md... updated
Checking BUSINESS_RULES.md... no changes
5. Create Missing Docs
For each standard doc type that doesn't exist:
Ask the user:
TERMINOLOGY.mddoesn't exist yet. Create it?
- Yes - Generate and upload
- No - Skip
If "Yes", create the doc:
mcp__aintentfirst__create_project_doc with:
- projectId
- name: "TERMINOLOGY.md"
- content: <generated markdown content>
Repeat for each missing doc type.
6. Summary
Display a summary of changes:
Documentation sync complete for: <project-name>
Updated:
- TERMINOLOGY.md (added 3 new terms)
- USER_FLOWS.md (added checkout flow)
Created:
- BUSINESS_RULES.md
Unchanged:
- SCREENS.md
The LLM will use these updated docs when asking clarifying questions on new tickets.
Doc Content Guidelines
TERMINOLOGY.md
Format each term as:
## Term Name
**Definition**: What this means in the context of this project.
**Usage**: Where/how this term is used in the application.
Focus on:
- Domain-specific nouns (entities, concepts)
- Status names and what they mean
- Role names and their permissions
- Any jargon unique to this project
SCREENS.md
Format each screen as:
## Screen Name
**Route**: `/path/to/screen`
**Purpose**: What users accomplish on this screen.
**Key Elements**:
- Element 1 - what it does
- Element 2 - what it does
USER_FLOWS.md
Format each flow as:
## Flow Name
**Goal**: What the user wants to accomplish.
**Steps**:
1. User does X on [Screen Name]
2. System responds with Y
3. User proceeds to [Next Screen]
4. ...
**Outcomes**:
- Success: What happens when flow completes
- Failure: What happens if something goes wrong
BUSINESS_RULES.md
Format each rule as:
## Rule Name
**Rule**: Clear statement of the constraint.
**Reason**: Why this rule exists.
**Enforcement**: Where/how this is enforced in the app.
Notes
- This command requires
/initto be run first - Only standard doc types are auto-synced; custom docs are preserved
- The LLM uses these docs to ask better clarifying questions
- Run this before creating tickets about new features you've built
Sponsors
Details
- Marketplace
- yvocilon/aintentfirst-plugin
- Author
- Yvo Cilon
- Category
- Productivity