Docs / Raw

Agent Task Index

Sourced from docs/ai/AGENT_TASK_INDEX.md

Edit on GitHub

Agent Task Index

This document lists common AI agent tasks with the relevant documentation and endpoints needed to complete them.

Machine-Readable Endpoints:

  • https://assistdocs.asimo.io/agent/index.json - Documentation metadata
  • https://assistdocs.asimo.io/agent/docs.json - Full document list with filtering
  • https://assistdocs.asimo.io/agent/tasks.json - Common agent tasks with commands
  • https://assistdocs.asimo.io/search-index.json - Full-text search index
  • https://assistdocs.asimo.io/agent/repo-index.json - Repository structure index
  • https://assistdocs.asimo.io/agent/repo/manifest.json - Key files manifest
  • https://assistdocs.asimo.io/agent/repo/files/{path}.json - Source file content
  • https://assistdocs.asimo.io/agent/doc-code-map.json - Doc ↔ code crosswalk mapping

Common Tasks

1. Understand Project Status

Goal: Get current state of all components

Key Documents:

API Endpoint:

curl https://assistdocs.asimo.io/agent/docs.json | jq '.[] | select(.category == "overview")'

2. Implement a Project Phase

Goal: Complete a development phase (0-15)

Key Documents:

Workflow:

  1. Check phase prerequisites in Implementation Status
  2. Read the specific phase document
  3. Follow Claude Execution Guide workflow
  4. Update Implementation Status when complete

3. Debug Backend Issues

Goal: Diagnose and fix API Gateway, database, or cache problems

Key Documents:

Quick Commands:

# Check API Gateway logs
docker logs voiceassist-server --tail 100

# Check health
curl http://localhost:8000/health

# Check database
psql -c "SELECT count(*) FROM pg_stat_activity WHERE datname = 'voiceassist'"

4. Debug Frontend Issues

Goal: Diagnose and fix React web app or admin panel problems

Key Documents:

Quick Commands:

# Check for TypeScript errors
cd apps/web-app && pnpm tsc --noEmit

# Run tests
pnpm test

# Development server
pnpm dev

5. Debug Voice/Realtime Issues

Goal: Diagnose WebSocket, STT, or TTS problems

Key Documents:

Key Files:

  • apps/web-app/src/hooks/useRealtimeVoiceSession.ts
  • apps/web-app/src/components/voice/VoiceModePanel.tsx
  • services/api-gateway/app/api/voice.py

6. Update Documentation

Goal: Add or modify documentation

Key Documents:

Workflow:

  1. Edit markdown files in docs/
  2. Add proper frontmatter with metadata (see Metadata Standard)
  3. Validate: cd apps/docs-site && pnpm validate:all
  4. Regenerate search index and agent JSON: pnpm generate-search-index && pnpm generate-agent-json
  5. Build: pnpm build
  6. Deploy: Copy out/ to /var/www/assistdocs.asimo.io/

7. Add New API Endpoint

Goal: Implement a new REST API route

Key Documents:

Key Paths:

  • Route handlers: services/api-gateway/app/api/
  • Services: services/api-gateway/app/services/
  • Models: services/api-gateway/app/models/
  • Tests: services/api-gateway/tests/

8. Work on Admin Panel

Goal: Implement admin panel features

Key Documents:

Key Paths:

  • Backend: services/api-gateway/app/api/admin_*.py
  • Frontend: apps/admin-panel/src/
  • Shared types: packages/types/src/admin/

Implementation Plan Phases:

  1. Phase 1: Backend-to-Admin Service Matrix
  2. Phase 2: Admin API Enhancement Plan
  3. Phase 3: Admin Panel UI Implementation
  4. Phase 4: API Client Integration
  5. Phase 5: Security & Compliance
  6. Phase 6: Testing Strategy
  7. Phase 7: Deployment & Rollout

Admin Feature Categories:

CategoryAPI PrefixUI Route
Voice/Realtime/api/admin/voice/*/voice
Integrations/api/admin/integrations/*/integrations
Tools/api/admin/tools/*/tools, /tools/logs
Security/PHI/api/admin/phi/*/security
Backups/DR/api/admin/backups/*/backups
Troubleshooting/api/admin/logs/*/troubleshooting

Critical Requirements:

  • All endpoints must enforce RBAC (admin or viewer role)
  • All mutations must emit audit logs
  • PHI must be masked in all responses
  • See Implementation Plan §5.6 for forbidden actions

9. Security/Compliance Work

Goal: HIPAA compliance, security hardening

Key Documents:

10. Infrastructure/Deployment

Goal: Docker, Kubernetes, monitoring setup

Key Documents:

11. Docs Health Audit

Goal: Assess documentation quality and identify improvement areas

Key Documents:

Workflow:

  1. Fetch health metrics: curl https://assistdocs.asimo.io/agent/health.json
  2. Run local validation: cd apps/docs-site && pnpm validate:all
  3. Check AI summary coverage: curl https://assistdocs.asimo.io/agent/docs-summary.json | jq '.stats'
  4. Identify stale docs from health.json category_freshness section
  5. Add missing ai_summary fields to docs targeting AI agents

Quick Commands:

cd apps/docs-site

# Run all validation checks
pnpm validate:all

# Check for docs missing ai_summary
pnpm validate:metadata 2>&1 | grep "Missing ai_summary"

# Regenerate agent JSON after fixes
pnpm generate-agent-json

Repository Navigation Tasks

These tasks leverage the machine-readable repository endpoints to explore and understand the codebase.

12. Discover Repository Components

Goal: List and understand all major components in the codebase

API Endpoints:

  • https://assistdocs.asimo.io/agent/repo-index.json - Full repository structure
  • https://assistdocs.asimo.io/agent/repo/manifest.json - Key files manifest

Workflow:

# List all component categories
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '.stats.by_component'

# Find all frontend components
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.component | startswith("frontend"))]'

# Find all backend services
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.component | startswith("backend"))]'

# Get language breakdown
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '.stats.by_language'

Key Documents:

13. Locate Feature Implementation

Goal: Given a feature name, find relevant implementation files

API Endpoints:

  • https://assistdocs.asimo.io/agent/repo-index.json - File paths by component
  • https://assistdocs.asimo.io/agent/repo/files/{encoded-path}.json - Source code content
  • https://assistdocs.asimo.io/search-index.json - Full-text search

Workflow:

  1. Search documentation for feature context:

    curl https://assistdocs.asimo.io/agent/docs.json | jq '.docs[] | select(.title | test("voice"; "i"))'

  2. Find implementation files by component:

    # Voice features are in backend/api-gateway and frontend/web-app
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | test("voice"; "i"))]'

  3. Get source code for specific file:

    # Path encoding: / → __ (double underscore)
# Example: services/api-gateway/app/api/voice.py → services__api-gateway__app__api__voice.py.json
curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__api__voice.py.json

  4. Cross-reference with documentation:

    curl https://assistdocs.asimo.io/agent/docs.json | jq '.docs[] | select(.tags | index("voice"))'

Key Documents:

14. Audit Implementation vs Documentation

Goal: Compare documentation claims against actual code implementation

API Endpoints:

  • https://assistdocs.asimo.io/agent/docs.json - Documentation metadata
  • https://assistdocs.asimo.io/agent/repo-index.json - Repository structure
  • https://assistdocs.asimo.io/agent/repo/files/{encoded-path}.json - Source code

Workflow:

  1. Identify feature documentation:

    curl https://assistdocs.asimo.io/agent/docs.json | jq '.docs[] | select(.category == "admin")'

  2. Extract documented paths/endpoints from docs

  3. Verify files exist in repo-index:

    curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | test("admin"))]'

  4. Fetch and compare source code:

    curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__api__admin.py.json | jq '.content'

  5. Report discrepancies:

    • Missing files referenced in docs
    • Undocumented endpoints in code
    • Version/status mismatches

Key Documents:

15. Explore Codebase by Language

Goal: Find all files of a specific programming language

API Endpoint:

  • https://assistdocs.asimo.io/agent/repo-index.json

Workflow:

# Find all TypeScript files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.language == "typescript")]'

# Find all Python files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.language == "python")]'

# Count files by language
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '.stats.by_language'

# Find configuration files (YAML, JSON, TOML)
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.language | . == "yaml" or . == "json" or . == "toml")]'

Supported Languages:

typescript, javascript, python, markdown, json, yaml, toml, html, css, scss, shell, dockerfile, terraform, prisma, graphql

16. Find Entry Points and Configuration

Goal: Quickly locate main entry points and config files

API Endpoint:

  • https://assistdocs.asimo.io/agent/repo/manifest.json - Curated key files

Workflow:

# Get all exported key files
curl https://assistdocs.asimo.io/agent/repo/manifest.json | jq '.files'

# Find package.json files (entry points)
curl https://assistdocs.asimo.io/agent/repo/manifest.json | jq '[.files[] | select(.path | endswith("package.json"))]'

# Find Python entry points
curl https://assistdocs.asimo.io/agent/repo/manifest.json | jq '[.files[] | select(.path | endswith("main.py"))]'

# Get root configuration files
curl https://assistdocs.asimo.io/agent/repo/manifest.json | jq '[.files[] | select(.path | contains("/") | not)]'

Key Files Categories:

CategoryExamples
Root Configpackage.json, turbo.json, docker-compose.yml
API Gatewaymain.py, config.py, requirements.txt
Web Appnext.config.js, page.tsx, layout.tsx
Admin Panelnext.config.js, page.tsx, layout.tsx
DocumentationSTART_HERE.md, AGENT_ONBOARDING.md

Doc-Code Crosswalk Tasks

These tasks use the /agent/doc-code-map.json endpoint to navigate between documentation and code.

17. Doc-Code Crosswalk Audit

Goal: Ensure docs' relatedPaths point to real files and key code files have documentation

API Endpoints:

  • https://assistdocs.asimo.io/agent/doc-code-map.json
  • https://assistdocs.asimo.io/agent/repo/manifest.json

Workflow:

# 1. Check for missing paths (relatedPaths that don't exist in repo)
curl https://assistdocs.asimo.io/agent/doc-code-map.json | jq '.meta.missing_paths'

# 2. Get stats on doc-code coverage
curl https://assistdocs.asimo.io/agent/doc-code-map.json | jq '.meta.stats'

# 3. Find key files in manifest that have no docs
curl https://assistdocs.asimo.io/agent/doc-code-map.json -o map.json
curl https://assistdocs.asimo.io/agent/repo/manifest.json | \
  jq --slurpfile map map.json '[.files[].path] - [($map[0].by_path | keys)[]]'

Report Format:

  • List paths in missing_paths that need fixing in source docs
  • List key manifest files without documentation
  • Recommend adding relatedPaths to important docs

Goal: Given a repo path, pull relevant docs and summarize the file's purpose

API Endpoints:

  • https://assistdocs.asimo.io/agent/doc-code-map.json
  • https://assistdocs.asimo.io/agent/docs.json
  • https://assistdocs.asimo.io/agent/repo/files/{encoded}.json

Workflow:

# Example: Explain services/api-gateway/app/api/voice.py

# 1. Find docs that reference this file
curl https://assistdocs.asimo.io/agent/doc-code-map.json | \
  jq '.by_path["services/api-gateway/app/api/voice.py"].docs'

# 2. Get those docs' ai_summary
SLUGS=$(curl -s https://assistdocs.asimo.io/agent/doc-code-map.json | \
  jq -r '.by_path["services/api-gateway/app/api/voice.py"].docs[]')
for slug in $SLUGS; do
  curl -s https://assistdocs.asimo.io/agent/docs.json | \
    jq --arg s "$slug" '.docs[] | select(.slug == $s) | {title, ai_summary}'
done

# 3. Get the file content
curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__api__voice.py.json | \
  jq '.content'

Output: Combine docs' ai_summary fields with file content to explain purpose.

19. Find Implementation for a Feature

Goal: Given a feature name, find both docs and code

API Endpoints:

  • https://assistdocs.asimo.io/agent/docs.json
  • https://assistdocs.asimo.io/agent/doc-code-map.json

Workflow:

# Example: Find everything about "voice mode"

# 1. Find docs mentioning the feature
curl https://assistdocs.asimo.io/agent/docs.json | \
  jq '[.docs[] | select(.title | test("voice"; "i")) | {slug, title, component, relatedPaths}]'

# 2. Get code files from those docs
curl https://assistdocs.asimo.io/agent/doc-code-map.json | \
  jq '[.by_doc_slug | to_entries[] | select(.key | test("voice"; "i")) | .value.relatedPaths] | flatten | unique'

# 3. Find docs for specific component
curl https://assistdocs.asimo.io/agent/doc-code-map.json | \
  jq '[.by_doc_slug | to_entries[] | select(.value.component == "backend/api-gateway") | .key]'

Filtering Documents by Task

Use the agent JSON API to filter documents:

// Fetch all docs
const response = await fetch("https://assistdocs.asimo.io/agent/docs.json");
const data = await response.json();

// Filter by category
const debuggingDocs = data.docs.filter((d) => d.category === "debugging");

// Filter by audience (use canonical 'ai-agents' value)
const agentDocs = data.docs.filter((d) => d.audience && d.audience.includes("ai-agents"));

// Filter by tag
const backendDocs = data.docs.filter((d) => d.tags && d.tags.includes("backend"));

// Find docs with ai_summary
const docsWithSummary = data.docs.filter((d) => d.ai_summary);
← All documentationHome
Beginning of guide
End of guide