Intent

git add src/auth/middleware.ts .intent/plans/auth-rewrite.md
git commit -m "Refactor auth middleware for session token compliance"

.intent/
  intent.json          ← project config
  plans/               ← active and historical plans
  decisions/           ← architectural decision records (ADRs)
  systems/             ← system / domain definitions
  constraints/         ← hard and soft constraints
  links/               ← auto-generated index (never edit manually)
    index.json

Meta-package. Installs both the CLI and the MCP server in one command. The recommended install for most projects.

Zod schemas and TypeScript types for all document formats. The shared type contract used by core, CLI, and MCP. Use this if you're building tooling on top of the .intent/ format.

All .intent/ file I/O, parsing, validation, git integration, and context management. Returns Result<T, IntentError> throughout — no silent failures. Not typically installed directly.

Commander.js CLI. A thin command layer — all business logic lives in core. Install directly if you only need the CLI and not the MCP server.

MCP server exposing 11 Intent tools via stdio. Configure once in your AI agent and it has access to your repository's full reasoning context. Install directly if you only need the server.

Dependency rule: schemas → core → cli / mcp. Core never imports CLI. Schemas never import core. All business logic belongs in core, not in command handlers.

# Recommended: installs CLI + MCP server in one go
npm install -g @dev-sixbyfive/intent

# Or with pnpm
pnpm add -g @dev-sixbyfive/intent

# CLI only
npm install -g @dev-sixbyfive/intent-cli

# MCP server only
npm install -g @dev-sixbyfive/intent-mcp

cd your-project
intent init
# Creates .intent/ with intent.json and all subdirectories
# Adds .intent/links/ to .gitignore

intent plan create auth-rewrite --title "Auth middleware rewrite" --system auth

intent decision add --title "Use short-lived JWTs over session tokens" --system auth
# Auto-increments the ID: DEC-0001, DEC-0002, …

git add src/auth/
intent review-diff
# Cross-references changed files against the links index
# Surfaces only plans and decisions relevant to this commit

{
  "mcpServers": {
    "intent": {
      "command": "npx",
      "args": ["@dev-sixbyfive/intent-mcp"]
    }
  }
}

---
id: plan-auth-rewrite
title: Auth middleware rewrite
type: plan
status: active          # draft | active | archived | superseded
created: 2024-01-15T09:00:00Z
updated: 2024-01-15T09:00:00Z
system: auth
decisions: [DEC-0001]
constraints: []
tags: [security, compliance]
---

## Goal

Replace the legacy session token middleware with short-lived JWTs.

## Reason

Legal flagged the current session token storage as non-compliant
with the new data residency requirements. Must be resolved before Q2 audit.

## Rules

- Tokens must expire in 15 minutes
- Refresh tokens stored in httpOnly cookies only
- No token data written to application logs

---
id: DEC-0001
title: Use short-lived JWTs over session tokens
type: decision
status: active          # draft | active | archived | superseded
created: 2024-01-15T09:00:00Z
updated: 2024-01-15T09:00:00Z
system: auth
plans: [plan-auth-rewrite]
tags: [security]
---

## Context

We need to replace the current session token approach. Options were:
opaque session tokens (existing), short-lived JWTs, or a
third-party auth provider.

## Decision

Short-lived JWTs (15 min) with httpOnly refresh tokens.

## Consequences

- Stateless auth — no session store required
- Must implement token refresh flow on the client
- All services need to validate JWTs independently

---
id: sys-auth
title: Auth system
type: system
created: 2024-01-10T09:00:00Z
updated: 2024-01-15T09:00:00Z
plans: [plan-auth-rewrite]
decisions: [DEC-0001]
tags: [security]
---

Session management, token issuance, and access control.
Shared by the web platform and the mobile app.

---
id: CON-0001
title: No token data written to application logs
type: constraint
severity: hard          # hard | soft
created: 2024-01-10T09:00:00Z
updated: 2024-01-10T09:00:00Z
system: auth
plans: [plan-auth-rewrite]
tags: [security, compliance]
---

Tokens, refresh tokens, and session identifiers must never
appear in application log output. Compliance requirement.

{
  "mcpServers": {
    "intent": {
      "command": "npx",
      "args": ["@dev-sixbyfive/intent-mcp"]
    }
  }
}

{
  "mcpServers": {
    "intent": {
      "command": "npx",
      "args": ["@dev-sixbyfive/intent-mcp"]
    }
  }
}

# ~/.codex/config.yaml
mcpServers:
  intent:
    command: npx
    args:
      - "@dev-sixbyfive/intent-mcp"

{
  "mcpServers": {
    "intent": {
      "command": "npx",
      "args": ["@dev-sixbyfive/intent-mcp"]
    }
  }
}

User: Implement the vendor listing limit

Agent calls: intent_agent_prepare "implement vendor listing limit"
  → scores plans/decisions by keyword relevance
  → returns plan-subscriptions, DEC-0007 (listing constraints),
    sys-marketplace

Agent implements accordingly — without asking the user to
re-explain the plan or constraints

Agent calls: intent_agent_review (after making changes)
  → changes covered by plan-subscriptions ✓
  → all files valid ✓
  → suggestDecision: false (changes were already linked)

# .github/workflows/intent-pr.yml
name: Intent PR Context

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  intent:
    name: Post intent context
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: SixByFive/intent/.github/actions/intent-pr@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          base-ref: origin/${{ github.base_ref }}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "intent agent prepare --hook"
          }
        ]
      }
    ]
  }
}