aimake Skill

Use this skill when integrating with aimake via MCP or leveraging its AI-powered delivery tools.

What is aimake?

aimake is an AI-powered delivery pipeline platform where cards are the deliverables, not tickets about work happening elsewhere. The AI drives work forward while humans bring taste and decision-making.

Key Concepts:

• Cards are atomic, independently deliverable work units
• Boards organize cards by type (Product, Engineering, Bugs, Docs)
• Stages are quality gates that enforce professional standards
• Card AI co-authors deliverables through conversation

Connecting via MCP

aimake exposes its functionality through MCP (Model Context Protocol).

Endpoints

GET  /mcp/manifest      # Returns available tool definitions
POST /mcp/tools/:name   # Executes a specific tool

Example Connection

// Fetch available tools
const manifest = await fetch('https://your-aimake-instance/mcp/manifest');
const tools = await manifest.json();

// Execute a tool
const result = await fetch('https://your-aimake-instance/mcp/tools/search_code_text', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    query: 'authentication',
    project_id: 'proj_123'
  })
});

Available MCP Tools

Code Tools

Search and analyze code in connected repositories.

| Tool | Description | Key Parameters | |------|-------------|----------------| | search_code_semantic | AI embeddings for conceptual matching | query, project_id | | search_code_text | Ripgrep-based pattern matching | query, project_id, file_pattern | | read_file | Get file content with line numbers | path, project_id | | list_directory | Browse repository structure | path, project_id | | get_file_tree | Complete code structure overview | project_id |

Example: Semantic Code Search

{
  "tool": "search_code_semantic",
  "input": {
    "query": "how is user authentication handled",
    "project_id": "proj_123"
  }
}

Documentation Tools

Access and search project documentation.

| Tool | Description | Key Parameters | |------|-------------|----------------| | search_docs | Full-text search across docs | query, project_id | | get_doc_page | Retrieve specific page | page_id, project_id | | list_docs | List all documentation pages | project_id |

Example: Search Documentation

{
  "tool": "search_docs",
  "input": {
    "query": "API rate limits",
    "project_id": "proj_123"
  }
}

Kanban Tools

Manage cards and projects in the delivery pipeline.

| Tool | Description | Key Parameters | |------|-------------|----------------| | query_cards | Search and filter cards | project_id, board, stage, search | | get_card | Get card details | card_id | | update_card_field | Update a card field | card_id, field, value | | move_card_to_stage | Move card to different stage | card_id, stage | | spawn_cards | Create new cards | project_id, board, cards[] | | get_project | Get project details | project_id |

Example: Query Cards

{
  "tool": "query_cards",
  "input": {
    "project_id": "proj_123",
    "board": "engineering",
    "stage": "in_progress",
    "search": "authentication"
  }
}

Example: Create Cards

{
  "tool": "spawn_cards",
  "input": {
    "project_id": "proj_123",
    "board": "engineering",
    "cards": [
      { "title": "Add OAuth2 support", "stage": "backlog" },
      { "title": "Implement refresh tokens", "stage": "backlog" }
    ]
  }
}

Understanding Boards and Stages

Board Types

| Board | Purpose | Use For | |-------|---------|---------| | Product | Specs and requirements | Feature definitions, user stories | | Engineering | Implementation tasks | Code work, technical tasks | | Bugs | Issue tracking | Bug reports, fixes | | Docs | Documentation | Project docs, guides |

Stage Progression

Cards move through stages as work progresses:

Product Board:

problemStatement → acceptanceCriteria → technicalReview → ready

Engineering Board:

backlog → in_progress → review → done

Atomicity Rules

Each card should be atomic and independently deliverable:

| Board | What's Atomic | |-------|---------------| | Product | One shippable experience ("Welcome screen" not "Onboarding") | | Engineering | One independently shippable component | | Bugs | One specific, reproducible problem |

Working with Card AI

Each card has an AI assistant that helps co-author the deliverable.

What Card AI Can Do

• Fill in card fields based on conversation
• Detect scope creep and suggest splitting cards
• Validate readiness before stage transitions
• Search code and docs for context
• Break down large work into atomic cards

Integration Pattern

When building tools that interact with aimake cards:

// 1. Get card context
const card = await mcpTool('get_card', { card_id: 'card_123' });

// 2. Search for relevant code
const codeContext = await mcpTool('search_code_semantic', {
  query: card.title,
  project_id: card.project_id
});

// 3. Update card with findings
await mcpTool('update_card_field', {
  card_id: 'card_123',
  field: 'technicalNotes',
  value: `Relevant files:\n${codeContext.results.map(r => r.path).join('\n')}`
});

Common Integration Patterns

Triage Agent

Use aimake to analyze and route incoming requests:

// 1. Search docs for relevant context
const docs = await mcpTool('search_docs', { query: userRequest, project_id });

// 2. Search code for implementation details
const code = await mcpTool('search_code_semantic', { query: userRequest, project_id });

// 3. Create appropriate card
await mcpTool('spawn_cards', {
  project_id,
  board: isFeature ? 'product' : 'bugs',
  cards: [{ title: summarize(userRequest), stage: 'backlog' }]
});

Context Retrieval

Pull relevant context from aimake for AI conversations:

// Get project overview
const project = await mcpTool('get_project', { project_id });
const fileTree = await mcpTool('get_file_tree', { project_id });
const docs = await mcpTool('list_docs', { project_id });

// Search for specific context
const relevantCode = await mcpTool('search_code_text', {
  query: 'class UserAuth',
  project_id
});

Progress Tracking

Query cards to understand project state:

// Get all in-progress work
const activeWork = await mcpTool('query_cards', {
  project_id,
  stage: 'in_progress'
});

// Get cards related to a feature
const featureCards = await mcpTool('query_cards', {
  project_id,
  search: 'authentication',
  boards: ['product', 'engineering', 'bugs']
});

Tool Response Format

All MCP tools return JSON responses:

// Success
{
  "success": true,
  "data": { /* tool-specific response */ }
}

// Error
{
  "success": false,
  "error": "Error message"
}

Code Search Response

{
  "results": [
    {
      "path": "src/auth/login.ts",
      "lines": "45-67",
      "content": "...",
      "score": 0.92
    }
  ]
}

Card Response

{
  "id": "card_123",
  "title": "Add OAuth2 support",
  "board": "engineering",
  "stage": "in_progress",
  "data": {
    "problemStatement": "...",
    "acceptanceCriteria": "...",
    "technicalNotes": "..."
  }
}