@ainative/cody-cli 0.2.7 → 0.2.8

package/.ainative/skills/mcp-builder/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: mcp-builder
+description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node.js (MCP SDK).
+---
+
+# MCP Builder Guide
+
+## What is an MCP Server?
+
+Model Context Protocol (MCP) servers expose tools that AI agents (Claude Code, Cursor, Windsurf, etc.) can call directly. You can build custom MCP servers to integrate any API or service.
+
+## Python -- FastMCP
+
+```bash
+pip install fastmcp
+```
+
+```python
+# my_mcp_server.py
+from fastmcp import FastMCP
+import requests
+
+mcp = FastMCP("my-tools")
+API_KEY = "your_api_key"
+BASE = "https://your-api.example.com"
+
+@mcp.tool()
+def get_status() -> dict:
+    """Get current service status."""
+    return requests.get(
+        f"{BASE}/api/v1/status",
+        headers={"X-API-Key": API_KEY}
+    ).json()
+
+@mcp.tool()
+def search_items(query: str, limit: int = 5) -> dict:
+    """Search items by query."""
+    return requests.post(
+        f"{BASE}/api/v1/search",
+        headers={"X-API-Key": API_KEY},
+        json={"query": query, "limit": limit}
+    ).json()
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+```bash
+python my_mcp_server.py
+```
+
+## Node.js -- MCP SDK
+
+```bash
+npm install @modelcontextprotocol/sdk
+```
+
+```typescript
+// server.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new Server(
+  { name: 'my-mcp-server', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler('tools/list', async () => ({
+  tools: [{
+    name: 'get_status',
+    description: 'Get current service status',
+    inputSchema: { type: 'object', properties: {} }
+  }]
+}));
+
+server.setRequestHandler('tools/call', async (request) => {
+  if (request.params.name === 'get_status') {
+    const resp = await fetch('https://your-api.example.com/api/v1/status', {
+      headers: { 'X-API-Key': process.env.API_KEY! }
+    });
+    return { content: [{ type: 'text', text: JSON.stringify(await resp.json()) }] };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Configure in Claude Code
+
+```json
+// .claude/mcp.json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "python",
+      "args": ["my_mcp_server.py"],
+      "env": { "API_KEY": "your_api_key" }
+    }
+  }
+}
+```
+
+For a published npm package:
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "npx",
+      "args": ["my-mcp-package"],
+      "env": { "API_KEY": "your_api_key" }
+    }
+  }
+}
+```
+
+## SKILL.md Format
+
+Every MCP tool should have a matching skill file so agents know when to call it:
+
+```markdown
+---
+name: my-tool-name
+description: One-line description. Use when (1) scenario, (2) scenario, (3) scenario.
+---
+
+# Tool Name
+
+Brief description and usage examples.
+```
+
+Place in `.claude/skills/my-tool-name/SKILL.md`.
+
+## Publish to npm
+
+```bash
+# package.json
+{
+  "name": "my-mcp-server",
+  "version": "1.0.0",
+  "bin": { "my-mcp-server": "./dist/server.js" },
+  "main": "./dist/server.js"
+}
+
+npm publish
+```
+
+## References
+
+- MCP spec: `https://modelcontextprotocol.io`

package/.claude/RAILWAY_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,118 @@
+# Railway Deployment Guide
+
+## Service Architecture
+
+Production environments can use a multi-service architecture on Railway:
+
+### Key Services
+
+1. **API Gateway** (e.g., Kong) - Routes requests to backend services
+2. **Backend** - Main application service (handles auth, users, billing, etc.)
+3. **CMS** - Content management (e.g., Strapi)
+4. **Database** - PostgreSQL database
+
+### Critical: Deploy to the Correct Service
+
+**ALWAYS deploy backend code to the correct backend service, NOT the gateway!**
+
+## Deployment Commands
+
+### 1. List All Services
+```bash
+railway status --json | jq -r '.services.edges[].node.name'
+```
+
+### 2. Deploy to Backend Service
+```bash
+# Option 1: Deploy with service flag (RECOMMENDED)
+railway up --detach --service "your-backend-service"
+
+# Option 2: Link to service first, then deploy
+railway link --service "your-backend-service"
+railway up --detach
+```
+
+### 3. Check Deployment Status
+```bash
+railway status --json | jq -r '.services.edges[] | select(.node.name == "your-service") | .node.serviceInstances.edges[0].node.latestDeployment'
+```
+
+## Common Mistakes to Avoid
+
+- **DON'T:** Deploy without specifying service (deploys to wrong service)
+- **DO:** Always specify the service explicitly
+- **DON'T:** Assume `railway up` knows which service based on the code
+- **DO:** Use Railway docs to understand service structure first
+
+## GitHub CI/CD Integration
+
+Railway can auto-deploy from GitHub when CI passes. If CI fails:
+
+### Option 1: Fix CI and Let Auto-Deploy Work
+```bash
+# Fix failing tests, commit fixes, push to main
+# Railway auto-deploys when CI passes
+```
+
+### Option 2: Force Deploy (Bypass CI)
+```bash
+# Use when change is critical and safe despite CI failures
+railway up --detach --service your-backend-service
+```
+
+## Verifying Deployment
+
+### 1. Check Health Endpoint
+```bash
+curl https://your-domain.com/health | jq
+```
+
+### 2. Check Railway Dashboard
+- Build logs: https://railway.com/project/{project-id}/service/{service-id}
+- Deployment status
+- Error logs if deployment failed
+
+## Database Connection Issues
+
+If you see "Database connection failed" after deployment:
+
+1. **Wait 2-3 minutes** - Service might still be starting
+2. **Check Railway logs** - Look for connection errors
+3. **Verify environment variables** - DATABASE_URL must be set correctly
+4. **Check database service status** - Ensure PostgreSQL is running
+
+## Troubleshooting
+
+### Issue: "Service not found"
+**Solution:** List services first, use exact service name
+```bash
+railway status --json | jq -r '.services.edges[].node.name'
+railway up --service your-service  # Use exact name from list
+```
+
+### Issue: "Multiple services found"
+**Solution:** Always use `--service` flag explicitly
+
+### Issue: Deployment succeeds but changes don't appear
+**Possible causes:**
+1. Deployed to wrong service (check service name)
+2. Code not committed to git (Railway deploys from git, not local files)
+3. Deployment still in progress (wait longer)
+4. Cache issue (try hard refresh or new incognito window)
+
+## Best Practices
+
+1. **Always verify service name before deploying**
+2. **Use explicit service flags**
+3. **Check deployment status after deploying**
+4. **Use Railway dashboard for detailed logs**
+
+## Quick Reference
+
+```bash
+# Deploy backend code
+railway up --detach --service "your-backend-service"
+
+# Check all services and their status
+railway status --json | jq -r '.services.edges[].node | {name, latestDeployment: .serviceInstances.edges[0].node.latestDeployment.status}'
+```

package/.claude/hooks/README.md

@@ -0,0 +1,68 @@
+# Git Hooks - File Placement & Commit Message Enforcement
+
+## Quick Install
+
+```bash
+# From your project root:
+bash .claude/hooks/install-hooks.sh
+```
+
+Or if using .ainative:
+```bash
+bash .ainative/hooks/install-hooks.sh
+```
+
+## What Gets Installed
+
+### 1. Pre-commit Hook
+**Blocks:**
+- .md files in root directory (except README.md, CLAUDE.md)
+- .sh scripts in root directory
+- .sh scripts in backend/ (except backend/start.sh)
+- .md files in src/backend/
+
+### 2. Commit-msg Hook
+**Blocks:**
+- "Claude", "Anthropic", "claude.com"
+- "ChatGPT", "OpenAI" (as code author)
+- "Copilot", "GitHub Copilot"
+- "Generated with", "Powered by" + third-party tools
+- "Co-Authored-By: Claude/ChatGPT/Copilot"
+
+## Testing
+
+After installation, test with:
+
+```bash
+# Test file placement (should block)
+touch test.md
+git add test.md
+git commit -m "test"
+
+# Expected: BLOCKED
+
+# Test commit message (should block)
+git commit -m "test
+
+Generated with Claude"
+
+# Expected: BLOCKED
+```
+
+## Manual Installation
+
+If the script doesn't work, install manually:
+
+```bash
+cp .claude/hooks/pre-commit .git/hooks/pre-commit
+cp .claude/hooks/commit-msg .git/hooks/commit-msg
+chmod +x .git/hooks/pre-commit
+chmod +x .git/hooks/commit-msg
+```
+
+## Related Documentation
+
+- `.ainative/CRITICAL_FILE_PLACEMENT_RULES.md`
+- `.ainative/git-rules.md`
+- `.claude/skills/file-placement/SKILL.md`
+- `.claude/skills/git-workflow/`

package/.claude/hooks/commit-msg

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Commit Message Hook - AI Attribution Enforcement
+# Blocks third-party AI tool attribution in commit messages
+
+COMMIT_MSG_FILE=$1
+
+echo "Checking commit message for AI attribution..."
+
+# Block third-party AI tool attribution
+if grep -qiE "(claude|anthropic|chatgpt|openai.*generated|copilot.*generated|co-authored-by:.*claude|co-authored-by:.*chatgpt|co-authored-by:.*copilot|generated with claude|generated with chatgpt|generated with.*https://claude\.com)" "$COMMIT_MSG_FILE"; then
+    echo "ERROR: Commit message contains FORBIDDEN third-party AI attribution!"
+    echo ""
+    echo "FORBIDDEN TERMS DETECTED:"
+    echo "  - Claude, Anthropic, claude.com"
+    echo "  - ChatGPT, OpenAI (as code author)"
+    echo "  - Copilot, GitHub Copilot"
+    echo "  - 'Generated with', 'Powered by' + third-party tools"
+    echo "  - 'Co-Authored-By: Claude/ChatGPT/Copilot'"
+    echo ""
+    echo "See .ainative/git-rules.md for complete guidelines"
+    echo ""
+    exit 1
+fi
+
+echo "Commit message: PASS"
+exit 0

package/.claude/hooks/install-hooks.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Install git hooks for file placement and commit message enforcement
+# Run from project root: bash .claude/hooks/install-hooks.sh
+
+set -e
+
+echo "Installing git hooks..."
+echo ""
+
+# Determine which folder we're in (.ainative or .claude)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOKS_SOURCE="$SCRIPT_DIR"
+
+# Check if we're in a git repository
+if [ ! -d ".git" ]; then
+    echo "Error: Not in a git repository root"
+    echo "   Run this script from your project root directory"
+    exit 1
+fi
+
+# Create .git/hooks directory if it doesn't exist
+mkdir -p .git/hooks
+
+# Install pre-commit hook
+echo "Installing pre-commit hook..."
+cp "$HOOKS_SOURCE/pre-commit" .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+echo "pre-commit hook installed"
+
+# Install commit-msg hook
+echo "Installing commit-msg hook..."
+cp "$HOOKS_SOURCE/commit-msg" .git/hooks/commit-msg
+chmod +x .git/hooks/commit-msg
+echo "commit-msg hook installed"
+
+echo ""
+echo "All hooks installed successfully!"
+echo ""
+echo "Enforcement active:"
+echo "  - File placement validation (pre-commit)"
+echo "  - Third-party attribution blocking (commit-msg)"
+echo ""
+echo "Test with:"
+echo "  touch test.md && git add test.md && git commit -m 'test'"
+echo "  (Should be blocked)"
+echo ""

package/.claude/hooks/pre-commit

@@ -0,0 +1,62 @@
+#!/bin/bash
+# File Placement Pre-commit Hook
+# Enforces file placement rules
+
+echo "Checking file placement rules..."
+
+# Check for .md files in root (except README.md and CLAUDE.md)
+VIOLATIONS=$(git diff --cached --name-only --diff-filter=A | grep -E '^[^/]+\.md$' | grep -v -E '^(README\.md|CLAUDE\.md)$' || true)
+if [ ! -z "$VIOLATIONS" ]; then
+  echo "BLOCKED: Attempting to add .md files to root directory:"
+  echo "$VIOLATIONS"
+  echo ""
+  echo "Per file-placement rules:"
+  echo "Only README.md and CLAUDE.md are allowed in root."
+  echo ""
+  echo "Move to appropriate docs/ subdirectory:"
+  echo "  - Product docs -> docs/product/"
+  echo "  - Planning docs -> docs/planning/"
+  echo "  - API docs -> docs/api/"
+  echo "  - Implementation -> docs/reports/"
+  echo "  - Issues -> docs/issues/"
+  echo "  - Backend docs -> docs/backend/"
+  echo ""
+  exit 1
+fi
+
+# Check for .sh files in root
+VIOLATIONS=$(git diff --cached --name-only --diff-filter=A | grep -E '^[^/]+\.sh$' || true)
+if [ ! -z "$VIOLATIONS" ]; then
+  echo "BLOCKED: Attempting to add .sh files to root directory:"
+  echo "$VIOLATIONS"
+  echo ""
+  echo "All scripts must be in scripts/ directory"
+  echo ""
+  exit 1
+fi
+
+# Check for .sh files in backend (except start.sh)
+VIOLATIONS=$(git diff --cached --name-only --diff-filter=A | grep -E '^backend/.*\.sh$' | grep -v 'backend/start.sh' || true)
+if [ ! -z "$VIOLATIONS" ]; then
+  echo "BLOCKED: Attempting to add .sh files to backend/ (except start.sh):"
+  echo "$VIOLATIONS"
+  echo ""
+  echo "All scripts must be in scripts/ directory"
+  echo "Exception: backend/start.sh only"
+  echo ""
+  exit 1
+fi
+
+# Check for .md files in src/backend/
+VIOLATIONS=$(git diff --cached --name-only --diff-filter=A | grep -E '^src/backend/.*\.md$' || true)
+if [ ! -z "$VIOLATIONS" ]; then
+  echo "BLOCKED: Attempting to add .md files to src/backend/:"
+  echo "$VIOLATIONS"
+  echo ""
+  echo "Documentation must be in docs/ directory"
+  echo ""
+  exit 1
+fi
+
+echo "File placement rules: PASS"
+exit 0

package/.claude/mcp.json.example

@@ -0,0 +1,31 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-github"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem"
+      ],
+      "args": [
+        "/path/to/your/project"
+      ]
+    }
+  }
+}

package/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(curl:*)",
+      "Bash(git:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(find:*)",
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(bun:*)",
+      "Bash(node:*)",
+      "Bash(python:*)",
+      "Bash(python3:*)",
+      "Bash(gh:*)",
+      "Bash(tree:*)",
+      "Bash(chmod:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)"
+    ],
+    "deny": []
+  }
+}

package/.claude/skills/ci-cd-compliance/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ci-cd-compliance
+description: CI/CD pipeline requirements and deployment standards. Use when (1) Setting up CI/CD pipelines, (2) Debugging CI failures, (3) Configuring deployment workflows, (4) Managing staging/production releases, (5) Investigating build failures. Covers CI gate requirements, merge policies, auto-deploy to staging, production approval process.
+---
+
+# CI/CD Compliance Rules
+
+## CI Gates Sequence
+
+**install -> lint/format -> typecheck -> unit -> integration -> (optional e2e) -> package**
+
+## Merge Policy
+
+* **Merge only if green**
+* Auto-deploy to **staging** on merge
+* Production requires tag/approval
+
+## CI Failure Handling
+
+When CI fails:
+1. **Explain root cause** in PR comment
+2. **Include the fix** in the same PR when feasible
+3. Don't merge until all gates pass
+
+## IDE Integration
+
+* Use built-in code actions and terminal to run tests/linters
+* Prefer **unified diffs** in responses so changes are patchable across IDEs
+* Attach artifacts (test output, screenshots, logs) whenever you assert a claim
+
+## Reference Files
+
+See `references/pipeline-requirements.md` for detailed CI configuration, gate definitions, and failure debugging guide.

package/.claude/skills/code-quality/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: code-quality
+description: Coding style standards, security guidelines, and accessibility requirements. Use when (1) Writing new code, (2) Reviewing code for style/security, (3) Implementing UI/UX features, (4) Addressing security concerns, (5) Ensuring accessibility compliance. Covers naming conventions, formatting, security best practices (no secrets/PII), accessibility standards (semantic HTML, keyboard nav), and responsive design.
+---
+
+# Code Quality Standards
+
+## Coding Style
+
+* **Naming:** camelCase for vars/functions; PascalCase for classes/types
+* **Formatting:** 4-space indentation; target <=80 chars (wrap thoughtfully)
+* **Comments:** Meaningful, current; delete stale comments
+* **Security:** Never log secrets/PII; validate inputs; least privilege by default
+* **Errors/Logs:** Explicit error types; structured logs by level; actionable messages
+
+## Accessibility & UX Quality
+
+* Favor semantic roles/labels; keyboard nav and focus order must work
+* Include responsive checks at **375, 768, 1024, 1440** with notes/screenshots
+* Use deterministic test IDs; avoid brittle CSS/XPath
+
+## Security & Compliance Guardrails
+
+* No real credentials in code, tests, or screenshots
+* Use test accounts/fixtures; redact secrets
+* Follow least-privilege and input validation
+* Document threat considerations in PR when relevant
+
+## Reference Files
+
+See `references/coding-style.md` for detailed style guide, formatting rules, comment standards.
+
+See `references/security-checklist.md` for security validation checklist, threat modeling, PII handling.
+
+See `references/accessibility-standards.md` for WCAG compliance, semantic HTML patterns, keyboard nav testing.

package/.claude/skills/file-placement/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: file-placement
+description: Enforces ZERO TOLERANCE file placement rules for documentation and scripts. Use when (1) Creating any .md file, (2) Creating any .sh script, (3) Organizing documentation, (4) Writing guides or reports, (5) Adding utility scripts. CRITICAL RULES - NEVER create .md files in root directories (except README.md, CLAUDE.md), NEVER create .sh scripts in backend (except start.sh), ALL documentation goes in docs/ subfolders, ALL scripts go in scripts/ folder.
+---
+
+# File Placement Rules
+
+## ZERO TOLERANCE FILE PLACEMENT
+
+### STRICT RULES
+
+* **FORBIDDEN:** Creating .md files in project root (except README.md, CLAUDE.md)
+* **FORBIDDEN:** Creating .md files in src/backend/ (except README.md)
+* **FORBIDDEN:** Creating scripts (.sh) in src/backend/ (except start.sh)
+
+### REQUIRED LOCATIONS
+
+## Backend Documentation -> `docs/`
+
+* **Issues/Bugs:** `docs/issues/ISSUE_*.md`, `docs/issues/BUG_*.md`, `docs/issues/ROOT_CAUSE_*.md`
+* **Testing/QA:** `docs/testing/*_TEST*.md`, `docs/testing/QA_*.md`
+* **API Documentation:** `docs/api/API_*.md`, `docs/api/*_ENDPOINTS*.md`
+* **Implementation Reports:** `docs/reports/*_IMPLEMENTATION*.md`, `docs/reports/*_SUMMARY.md`
+* **Deployment:** `docs/deployment/DEPLOYMENT_*.md`, `docs/deployment/RAILWAY_*.md`
+* **Quick References:** `docs/quick-reference/*_QUICK_*.md`, `docs/quick-reference/*_REFERENCE.md`
+* **Development Guides:** `docs/development-guides/CODING_*.md`, `docs/development-guides/*_GUIDE.md`
+* **Planning:** `docs/planning/PRD_*.md`, `docs/planning/BACKLOG*.md`
+
+## Scripts -> `scripts/`
+
+* **ALL test scripts:** `scripts/test_*.sh`
+* **ALL migration scripts:** `scripts/*_migration.sh`
+* **ALL monitoring scripts:** `scripts/monitor_*.sh`
+* **ALL utility scripts:** `scripts/*.sh`
+
+## ENFORCEMENT WORKFLOW
+
+Before creating ANY .md file or .sh script, you MUST:
+
+1. Check if you're creating it in a root directory
+2. If yes, STOP and use the appropriate docs/ or scripts/ subfolder
+3. Choose the correct category based on filename patterns above
+4. Create in the correct location FIRST TIME, not in root then move later
+
+## VIOLATION CONSEQUENCES
+
+Creating documentation in root directories causes:
+
+* Project clutter and disorganization
+* Wasted time reorganizing files
+* Inconsistent documentation structure
+* Developer frustration
+* Loss of findability for important docs
+
+**THIS IS A ZERO-TOLERANCE RULE. ALWAYS use docs/ or scripts/ subfolders.**
+
+## Reference Files
+
+See `references/directory-mapping.md` for complete mapping table of filename patterns to required directory locations.