ai-dev-tasks Cursor Rules

# Cursor Rules & Instructions
> **Auto-Generated**: This file is synchronized from `instructions/`. Do not edit manually.


<!-- BEGIN_GENERATED_INSTRUCTIONS -->
# AI Agent Operational Guide & Governance

> **Context**: This repository (`ai-dev-tasks`) is a shared **framework/submodule** used by other projects.
> Agents operating here are **Framework Contributors**, not Consumer Users.

## 1. 🤖 Core Mandates & Governance

### **Claudia is Boss**

- **Authority**: If `claudia-claude-code-agent` is running, respect her "STOP" commands immediately.
- **Coordination**: Claudia coordinates multi-agent workflows. Defer to her judgment on conflicts.
- **Monitoring**: Ensure Claudia is monitoring the session if possible.

### **Agent-First Workflow**

- **Consult First**: Before starting any significant task, ask: "Which agent can help with this?"
- **Delegation**:
  - **Script Logic**: Use `code-reviewer`
  - **Auth/Security**: Use `security-reviewer`
  - **Architecture**: Use `cto-agent`
  - **Docs/Specs**: Use `spec-writer`
  - **Requirements**: Use `business-analyst`
- **Reference**: See `AGENTS.md` or `docs/reference/AGENT_REFERENCE.md` for full capabilities.

### **95% Certainty Rule**

- Do not proceed with an action unless you are >95% certain.
- If uncertain, ask clarifying questions or consult a specialized agent.

---

## 2. 📚 Documentation Retrieval Policy

### **Context7 Integration**

- **Mandate**: When using external libraries, APIs, or frameworks, **ALWAYS** retrieve up-to-date documentation via Context7 first.
- **Precedence**: If Context7 retrieved docs conflict with your training data, **trust Context7**.

### **Installation & Usage**

1.  **Remote Connection (Recommended)**:
    - URL: `https://mcp.context7.com/mcp`
    - Header: `CONTEXT7_API_KEY` (Get from user or environment)
2.  **Local Connection**:
    - Command: `npx -y @upstash/context7-mcp`

---

## 3. 📝 Logging & Attribution Standards

### **Task Logging**

- **Location**: `docs/logs/TASK_LOG.md` (in the **consumer project**, NOT in `ai-dev-tasks`).
- **Format**: strictly adhere to the `START LOG` / `END LOG` block format.
- **Command**: Use `/log-task` to ensure compliance.

### **Attribution Policy**

- **Human Accountability**: All deliverables must appear authored by the team.
- **Credit**: "FutureTranz Development Team"
- **Forbidden Phrases**:
  - ❌ "Generated by AI"
  - ❌ "Co-authored by Cursor"
  - ❌ "Created with Cursor"
- **Commit Messages**: Do NOT add "Co-authored-by: [AI]" trailers.

---

## 4. 🛡️ Pre-Change Safety

- **Read First**: Always read `README.md` and `docs/guides/CLAUDE.md` before making structural changes.
- **Destructive Actions**: Stop and ask for confirmation before `rm`, `mv`, or overwriting core scripts.
- **Permission Gate**: Before committing/pushing, confirm:
  1.  Branch name
  2.  Commit summary
  3.  Intent to push/PR

---

## 5. 🏛️ Project Governance Rules

### **Mandatory Business Plan**

- **Trigger**: Project Kickoff AND Pre-Release.
- **Action**: Run `/create-business-plan`.
- **Constraint**: Do NOT start major coding until a business plan exists in `docs/business-plans/`.
- **Validation**: Plan must have Branding applied and Assumptions tagged.

### **Portfolio & Inventory**

- **Trigger**: Project Kickoff AND Pre-Release.
- **Action**: Run `/sync-portfolio-inventory`.
- **Requirement**: Ensure this repo is listed in `FutureTranz-Inc/github-portfolio-tracker`.

### **Autocoder Integration**

- **Trigger**: After Portfolio Inventory update.
- **Action**: Run `/sync-autocoder-features`.
- **Requirement**: All GitHub Issues must be synced to Autocoder's `features.db` for scheduling.

### **GitHub Lifecycle Integration (NEW)**

- **Requirement**: Every parent task in a task list MUST have a corresponding GitHub Issue.
- **Requirement**: Every task implementation MUST go through a Pull Request (PR) lifecycle:
  1. Create feature branch.
  2. Implement and commit.
  3. Create PR and request review from `@claudia` or specified expert agents.
  4. Debug and refine based on review.
  5. Merge and close once bug-free.

### **Research Integrity (3-Agent Consensus)**

- **Rule**: Any numeric claim, fact, or metric must be verified by 3 independent agents.
- **Process**:
  1.  **Agent A**: Research & Cite.
  2.  **Agent B**: Verify & Challenge.
  3.  **Agent C**: Resolve & Conclude.
- **Fallback**: If no consensus, mark as "Unknown" or "To Be Verified".

### **Lightweight Dependency Policy**

- **Rule**: No heavy daemons (Postgres, Redis, etc.) installed directly on the host.
- **Requirement**: Use Docker for all heavy dependencies.
- **Verification**: Run `/verify-no-heavy-deps`.

# Standard Commands & Tools

## 🛠️ Build, Lint & Test (Framework)

Since this is a documentation and script repository, "building" and "testing" primarily involves validation scripts.

### **Validation (Mandatory)**

Run these commands before committing any changes:

```bash
# 1. Check for AI Attribution Violations (CRITICAL)
./scripts/ci-check-attribution.sh
# Must return: "✅ AI Attribution Policy Check Passed"

# 2. Verify Script Permissions
chmod +x scripts/*.sh
```

### **Linting Recommendations**

- **Bash Scripts**: Use `shellcheck` if available.
  ```bash
  shellcheck scripts/*.sh
  ```
- **Markdown**: Ensure GitHub Flavored Markdown compatibility.

---

## 🤖 Agent Commands (Slash Commands)

These commands are available in Claude Code and should be adopted by other agents where possible.

### **/agent-help**

**Purpose**: Consult the MCP agent ecosystem to get expert assistance.
**Usage**: `/agent-help`
**Details**: Lists available agents (CFO, CTO, Security Reviewer, etc.) and provides a decision tree for selection.

### **/create-prd**

**Purpose**: Start building a new feature Product Requirement Document (PRD).
**Usage**: `/create-prd` -> "I want to build..."
**Source**: `ai-dev-tasks/workflow/create-prd.md`
**Output**: `docs/prd/[n]-prd-[feature].md`

### **/generate-tasks**

**Purpose**: Convert a PRD into actionable, granular tasks.
**Usage**: `/generate-tasks` (will prompt for PRD selection)
**Source**: `ai-dev-tasks/workflow/generate-tasks.md`
**Output**: `docs/tasks/tasks-[prd-filename].md`

### **/process-task-list**

**Purpose**: Methodically implement tasks one by one with review gates.
**Usage**: `/process-task-list` -> Select task list -> "Start with 1.1"
**Source**: `ai-dev-tasks/workflow/process-task-list.md`
**Workflow**: Read -> Plan -> Consult -> Implement -> Test -> Review -> Document.

### **/log-task**

**Purpose**: Record task completion in the enterprise audit trail.
**Usage**: `/log-task` -> Enter task details.
**Target**: `docs/logs/TASK_LOG.md` (in consumer project).
**Format**: Strict `START LOG` / `END LOG` block with no AI attribution.

### **/repo-stats**

**Purpose**: Report repository statistics to the portfolio tracker.
**Usage**: `/repo-stats`
**Action**: Runs `.cursor/hooks/report-repo-stats.sh`.

### **/create-business-plan**

**Purpose**: Generate an investor-ready Business Plan with branding and research.
**Usage**: `/create-business-plan`
**Source**: `ai-dev-tasks/features/create-business-plan/prompts.md`
**Output**: `docs/business-plans/[YYYYMMDD]-business-plan-[project-name].md`
**Constraint**: Mandatory at Project Kickoff and Pre-Release.

### **/sync-portfolio-inventory**

**Purpose**: Ensure this repository is listed in the GitHub Portfolio Tracker.
**Usage**: `/sync-portfolio-inventory`
**Source**: `ai-dev-tasks/scripts/sync-portfolio-inventory.sh`
**Requirement**: Mandatory for all projects.

### **/sync-autocoder-features**

**Purpose**: Sync GitHub Issues to Autocoder's scheduling database.
**Usage**: `/sync-autocoder-features`
**Source**: `ai-dev-tasks/scripts/sync-autocoder-features-db.py`
**Requirement**: Mandatory for all projects with open issues.

### **/verify-no-heavy-deps**

**Purpose**: Check for forbidden heavyweight dependencies (Postgres, Redis outside Docker).
**Usage**: `/verify-no-heavy-deps`
**Source**: `ai-dev-tasks/scripts/verify-no-heavy-deps.sh`
**Policy**: Lightweight Dependencies Policy.

### **/sync-org-forks**

**Purpose**: Distribute `ai-dev-tasks` to all GitHub Orgs, apply branding, and install sync workflow.
**Usage**: `./scripts/sync-to-org-forks.sh`
**Source**: `ai-dev-tasks/scripts/sync-to-org-forks.sh`
**Requirement**: Run when setting up a new org or updating the ecosystem.

### **/sync-forks-cli**

**Purpose**: Force-pull upstream changes to all org forks using GH CLI.
**Usage**: `./scripts/sync-forks-cli.sh`
**Source**: `ai-dev-tasks/scripts/sync-forks-cli.sh`

### **/sync-forks-workflow**

**Purpose**: Trigger the update workflow across all org forks.
**Usage**: `./scripts/sync-forks-workflow.sh`
**Source**: `ai-dev-tasks/scripts/sync-forks-workflow.sh`
<!-- END_GENERATED_INSTRUCTIONS -->