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": "..."
  }
}