### Run Development Server

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/admin-portal/README.md

Start the Next.js development server for the client-website.

```bash
npm -w client-website run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/admin-portal/README.md

Install project dependencies from the repository root.

```bash
npm install
```

--------------------------------

### CDK Orchestrator Examples

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts/README.md

Examples demonstrating common CDK orchestrator commands. Use --dry-run to preview changes and --auto-approve for non-interactive environments.

```bash
# Check current state
node scripts/cdk.mjs status
```

```bash
# Deploy infrastructure stacks to dev
node scripts/cdk.mjs deploy infra --auto-approve
```

```bash
# Deploy all stacks to production
node scripts/cdk.mjs deploy all --prod --auto-approve
```

```bash
# Pull outputs from deployed stacks
node scripts/cdk.mjs outputs infra
```

```bash
# Full preparation: build + copy assets + pull outputs
node scripts/cdk.mjs prepare
```

```bash
# Bootstrap the CDKTF backend
node scripts/cdk.mjs bootstrap --auto-approve
```

--------------------------------

### CDK Stack Composition Example

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Example of composing a CDKTF ApiStack, including setting up a standard backend and generating user/verification and security tables.

```typescript
// cdk/platform-cdk/src/stacks/api-stack/index.ts — example stack composition
import { TerraformStack } from 'cdktf';
import { StandardBackend } from '../../utils/standard-backend';
import { generateUserAndVerificationTable } from './generate-user-and-verification-table';
import { generateSecurityTables } from './generate-security-tables';

export class ApiStack extends TerraformStack {
  constructor(scope: Construct, id: string, props: ApiStackProps) {
    super(scope, id);
    new StandardBackend(this, id, props.region);  // S3 remote state
    generateUserAndVerificationTable(this, props.region);
    generateSecurityTables(this, props.region);   // rate-limit / session tables
  }
}
```

--------------------------------

### Run Backend in Development

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/README.md

Starts the Express backend server in development mode using Vite SSR. Ensure CDK outputs are generated before running.

```bash
npm -w node-server run dev
```

--------------------------------

### Deploy a single stack

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/cdk/platform-cdk/README.md

Use this to deploy a specific stack by prefixing the stack name. Example: STACK=myapp-api-stack.

```bash
STACK=myapp-api-stack npm -w @cdk/platform-cdk run cdk:deploy:dev
```

--------------------------------

### CDK Orchestrator Bootstrap Backend

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Initializes the CDKTF backend, typically setting up necessary S3 buckets and DynamoDB tables for state management. Use `--auto-approve` for automated setup.

```bash
node scripts/cdk.mjs bootstrap --auto-approve
```

--------------------------------

### Get Project by ID Response (200 OK)

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Response for retrieving a specific project by its ID.

```json
{
  "id": "proj-123",
  "name": "Project Name",
  "status": "active",
  "specGroupCount": 5,
  "health": "healthy",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

--------------------------------

### Response for Dispatched Agent Task

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

This is an example of a successful response (201 Created) when an agent task is dispatched.

```json
{
  "task": {
    "id": "task-123",
    "specGroupId": "sg-123",
    "action": "implement",
    "status": "DISPATCHED",
    "webhookUrl": "https://agent-endpoint.example.com",
    "context": {
      "specGroupId": "sg-123",
      "specGroupName": "Feature Spec",
      "triggeredBy": "system",
      "triggeredAt": "2024-01-15T10:30:00.000Z"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "message": "Implementation task dispatched successfully"
}
```

--------------------------------

### CDKTF Stack Deployment Commands

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Commands for installing, bootstrapping, deploying, and generating output files for CDKTF stacks. Used for provisioning AWS resources and generating application configuration.

```bash
# Install & bootstrap state backend (S3 + DynamoDB lock table)
npm -w @cdk/platform-cdk run cdk:bootstrap:dev

# Deploy individual stacks
npm -w @cdk/platform-cdk run cdk:deploy:dev api-stack          # Users, SpecGroups, security tables
npm -w @cdk/platform-cdk run cdk:deploy:dev analytics-stack    # EventBridge bus, DAU/MAU tables
npm -w @cdk/platform-cdk run cdk:deploy:dev analytics-lambda-stack  # Lambda function
npm -w @cdk/platform-cdk run cdk:deploy:dev client-website-stack    # CloudFront + S3

# Generate output files for local dev (consumed by node-server and analytics-lambda)
npm -w @cdk/platform-cdk run cdk:output:dev api-stack
npm -w @cdk/platform-cdk run cdk:output:dev analytics-stack

# Copy CDK outputs into each workspace for local dev
npm -w node-server run copy:cdk-outputs
npm -w analytics-lambda run copy:cdk-outputs
```

--------------------------------

### GET /api/projects/:id

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Fetches a single project by its ID. Requires a valid `dashboard_session` cookie.

```APIDOC
## GET /api/projects/:id — Get single project

### Description
Fetches one project by ID. Returns `404` with `{ "error": "Project with id {id} not found" }` if absent.

### Method
GET

### Endpoint
/api/projects/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

#### Cookies
- **dashboard_session** (string) - Required - The session cookie for authentication.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the project.
- **name** (string) - The name of the project.
- **status** (string) - The current status of the project ('active' | 'archived' | 'draft').
- **health** (string) - The computed health indicator of the project ('green' | 'yellow' | 'red').
- **specGroupCount** (number) - The number of spec groups associated with the project.
- **specGroupSummary** (object) - Summary of spec groups.
  - **total** (number) - Total number of spec groups.
  - **byState** (object) - Count of spec groups by their state.
  - **allGatesPassed** (number) - Number of spec groups where all gates passed.
  - **criticalGatesFailed** (number) - Number of spec groups with critical gates failed.
- **createdAt** (string) - ISO 8601 timestamp of when the project was created.
- **updatedAt** (string) - ISO 8601 timestamp of when the project was last updated.

#### Error Response (404)
- **error** (string) - Message indicating the project was not found.

### Response Example
```json
{
  "id": "ai-eng-dashboard",
  "name": "Ai Eng Dashboard",
  "status": "active",
  "health": "yellow",
  "specGroupCount": 5,
  "specGroupSummary": { "total": 5, "byState": { "DRAFT": 1, "IN_PROGRESS": 4 }, "allGatesPassed": 0, "criticalGatesFailed": 2 },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```
```

--------------------------------

### Output stack JSON for app consumption

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/cdk/platform-cdk/README.md

Generates JSON output for stacks, useful for application consumption. Example for API stack.

```bash
npm -w @cdk/platform-cdk run cdk:output:dev myapp-api-stack
```

--------------------------------

### JavaScript WebSocket Client Implementation

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Example JavaScript class for connecting to the agent status WebSocket, subscribing to tasks, sending messages, and handling incoming updates. Includes automatic reconnection logic.

```javascript
class AgentStatusWebSocket {
  constructor(url) {
    this.url = url;
    this.ws = null;
    this.subscriptions = new Set();
  }

  connect() {
    this.ws = new WebSocket(this.url);

    this.ws.onopen = () => {
      console.log('Connected');
      // Resubscribe to previous tasks
      this.subscriptions.forEach(taskId => {
        this.subscribe(taskId);
      });
    };

    this.ws.onmessage = (event) => {
      const message = JSON.parse(event.data);
      this.handleMessage(message);
    };

    this.ws.onclose = (event) => {
      if (event.code === 4001) {
        console.error('Unauthorized - session invalid');
        return;
      }
      // Reconnect after delay
      setTimeout(() => this.connect(), 5000);
    };
  }

  subscribe(taskId) {
    this.subscriptions.add(taskId);
    this.send({
      type: 'SUBSCRIBE',
      payload: { taskId }
    });
  }

  unsubscribe(taskId) {
    this.subscriptions.delete(taskId);
    this.send({
      type: 'UNSUBSCRIBE',
      payload: { taskId }
    });
  }

  send(message) {
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(message));
    }
  }

  handleMessage(message) {
    switch (message.type) {
      case 'TASK_STATUS_UPDATE':
        console.log('Task update:', message.payload);
        break;
      case 'CONNECTION_STATUS':
        console.log('Connected:', message.payload.connected);
        break;
    }
  }
}

// Usage
const ws = new AgentStatusWebSocket('ws://localhost:3001/ws/agent-status');
ws.connect();
ws.subscribe('task-123');
```

--------------------------------

### Get Single Project by ID (REST API)

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Fetches a specific project by its ID. Returns a 404 error if the project is not found. Requires a valid `dashboard_session` cookie.

```bash
curl http://localhost:3001/api/projects/ai-eng-dashboard -b cookies.txt

# Response 200 OK — same shape as a single item from GET /api/projects
{
  "id": "ai-eng-dashboard",
  "name": "Ai Eng Dashboard",
  "status": "active",
  "health": "yellow",
  "specGroupCount": 5,
  "specGroupSummary": { "total": 5, "byState": { "DRAFT": 1, "IN_PROGRESS": 4 }, "allGatesPassed": 0, "criticalGatesFailed": 2 },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

--------------------------------

### Agent Task Logs Response (JSON)

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Example JSON response for retrieving agent task logs. Includes task ID and a list of log entries with level, message, and timestamp.

```json
{
  "taskId": "task-123",
  "logs": [
    {
      "level": "info",
      "message": "Task started",
      "timestamp": "2024-01-15T10:30:00.000Z"
    },
    {
      "level": "info",
      "message": "Processing file 1/10",
      "timestamp": "2024-01-15T10:30:05.000Z"
    }
  ]
}
```

--------------------------------

### Health Check Response (200 OK)

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Example response for a successful health check. Includes service status, timestamp, version, and component health.

```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "0.0.1",
  "components": {
    "dynamodb": {
      "status": "healthy",
      "latencyMs": 45
    }
  }
}
```

--------------------------------

### Run Production Server Preview

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/README.md

Runs the production-built server using the production environment variables.

```bash
npm -w node-server run preview
```

--------------------------------

### GET /api/health

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Returns the operational status of the server and its components. No authentication required.

```APIDOC
## GET /api/health — Server health check

### Description
Returns the operational status of the server and its components. No authentication required.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - Operational status of the server ('healthy' | 'degraded' | 'unhealthy')
- **timestamp** (string) - ISO 8601 timestamp of the health check
- **version** (string) - The current version of the server
- **components** (object) - Status of various server components
  - **dynamodb** (object)
    - **status** (string) - Status of the DynamoDB component
    - **latencyMs** (number) - Latency in milliseconds for DynamoDB operations

### Response Example
```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "0.0.1",
  "components": {
    "dynamodb": {
      "status": "healthy",
      "latencyMs": 45
    }
  }
}
```
```

--------------------------------

### GET /api/auth/session

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Verifies the active user session by checking for a valid `dashboard_session` cookie.

```APIDOC
## GET /api/auth/session — Verify active session

### Description
Verifies the active user session by checking for a valid `dashboard_session` cookie.

### Method
GET

### Endpoint
/api/auth/session

### Parameters
#### Cookies
- **dashboard_session** (string) - Required - The session cookie to verify.

### Response
#### Success Response (200)
- **authenticated** (boolean) - True if the session is authenticated, false otherwise.

#### Error Response (401)
- Returns 401 Unauthorized if the session is not authenticated.

### Response Example
```json
{ "authenticated": true }
```
```

--------------------------------

### Serve Production Build

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/admin-portal/README.md

Serve the production-ready build of the Next.js application.

```bash
npm -w client-website run start
```

--------------------------------

### Full Deploy Sequence

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Executes a comprehensive deployment process that includes preparation (build, copy assets, pull outputs) followed by deploying all stacks.

```bash
node scripts/cdk.mjs prepare
node scripts/cdk.mjs deploy all --auto-approve
```

--------------------------------

### Migrate to bootstrapped backend

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/cdk/platform-cdk/README.md

Use this command when migrating to a bootstrapped backend. Review the script before execution.

```bash
npm -w @cdk/platform-cdk run cdk:bootstrap:migrate:dev
```

--------------------------------

### Clean and Deploy Sequence

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Performs a clean deployment by removing existing artifacts, reinstalling dependencies, preparing the environment, deploying all stacks, and running tests.

```bash
npm run clean
npm i
node scripts/cdk.mjs prepare
node scripts/cdk.mjs deploy all --auto-approve
npm run test
```

--------------------------------

### CDK Orchestrator Full Preparation

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Performs a complete preparation cycle, including building applications, copying assets, and pulling stack outputs. This ensures the environment is ready for deployment.

```bash
node scripts/cdk.mjs prepare
```

--------------------------------

### Retryable Error Response

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Example of a JSON response for an error that can be retried by the client. Includes a 'retryable' flag set to true.

```json
{
  "error": "Webhook dispatch failed",
  "retryable": true
}
```

--------------------------------

### GET /api/projects

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Returns all projects with spec group counts and computed health indicators. Requires a valid `dashboard_session` cookie.

```APIDOC
## GET /api/projects — List all projects

### Description
Returns all projects with spec group counts and computed health indicators. Requires a valid `dashboard_session` cookie.

### Method
GET

### Endpoint
/api/projects

### Parameters
#### Cookies
- **dashboard_session** (string) - Required - The session cookie for authentication.

### Response
#### Success Response (200)
- **projects** (array) - An array of project objects.
  - **id** (string) - Unique identifier for the project.
  - **name** (string) - The name of the project.
  - **description** (string) - A brief description of the project.
  - **status** (string) - The current status of the project ('active' | 'archived' | 'draft').
  - **health** (string) - The computed health indicator of the project ('green' | 'yellow' | 'red').
  - **specGroupCount** (number) - The number of spec groups associated with the project.
  - **specGroupSummary** (object) - Summary of spec groups.
    - **total** (number) - Total number of spec groups.
    - **byState** (object) - Count of spec groups by their state.
    - **allGatesPassed** (number) - Number of spec groups where all gates passed.
    - **criticalGatesFailed** (number) - Number of spec groups with critical gates failed.
  - **createdAt** (string) - ISO 8601 timestamp of when the project was created.
  - **updatedAt** (string) - ISO 8601 timestamp of when the project was last updated.
- **total** (number) - The total number of projects.

### Response Example
```json
{
  "projects": [
    {
      "id": "ai-eng-dashboard",
      "name": "Ai Eng Dashboard",
      "description": "Main dashboard project",
      "status": "active",
      "health": "green",
      "specGroupCount": 8,
      "specGroupSummary": {
        "total": 8,
        "byState": { "DRAFT": 2, "IN_PROGRESS": 3, "CONVERGED": 2, "MERGED": 1 },
        "allGatesPassed": 3,
        "criticalGatesFailed": 0
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}
```
```

--------------------------------

### List Projects Response (200 OK)

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Response containing a list of projects with their details.

```json
{
  "projects": [
    {
      "id": "proj-123",
      "name": "Project Name",
      "status": "active",
      "specGroupCount": 5,
      "health": "healthy",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}
```

--------------------------------

### Deploy dev stacks

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/cdk/platform-cdk/README.md

Execute this command to deploy all stacks in the development environment.

```bash
npm -w @cdk/platform-cdk run cdk:deploy:dev
```

--------------------------------

### Get Agent Task Logs

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieves the logs for a specific agent task. Authentication is required using a session cookie.

```APIDOC
## GET /api/agent-tasks/:id/logs

### Description
Get agent task logs.

### Method
GET

### Endpoint
/api/agent-tasks/:id/logs

### Parameters
#### Path Parameters
- **id** (string) - Required - Agent Task ID

### Response
#### Success Response (200 OK)
- **taskId** (string) - The ID of the task.
- **logs** (array) - An array of log objects.
  - **level** (string) - The log level (e.g., debug, info, warn, error).
  - **message** (string) - The log message.
  - **timestamp** (string) - The timestamp of the log entry.

### Response Example
```json
{
  "taskId": "task-123",
  "logs": [
    {
      "level": "info",
      "message": "Task started",
      "timestamp": "2024-01-15T10:30:00.000Z"
    },
    {
      "level": "info",
      "message": "Processing file 1/10",
      "timestamp": "2024-01-15T10:30:05.000Z"
    }
  ]
}
```

### Error Responses
#### Not Found Response (404)
- **Error**: `Agent task with id {id} not found` - Task does not exist.
```

--------------------------------

### Get Agent Task by ID

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieve the details of an agent task using its unique ID. Requires session authentication.

```json
{
  "task": {
    "id": "task-123",
    "specGroupId": "sg-123",
    "action": "implement",
    "status": "RUNNING",
    "webhookUrl": "https://agent-endpoint.example.com",
    "context": {
      "specGroupId": "sg-123",
      "specGroupName": "Feature Spec",
      "triggeredBy": "system",
      "triggeredAt": "2024-01-15T10:30:00.000Z"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

--------------------------------

### List Available Sequences

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Lists all predefined command sequences available for execution. These sequences automate common multi-step workflows.

```bash
npm run sequence -- list
```

--------------------------------

### Build and Deploy Lambda Sequence

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Automates the build and deployment of the API lambda. This sequence includes environment variable decryption, deployment, and re-encryption.

```bash
npm -w node-server run decrypt-envs
node scripts/cdk.mjs deploy myapp-api-lambda-stack --auto-approve
npm -w node-server run encrypt-envs
```

--------------------------------

### Get GitHub Issues Linked to Project

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieves a list of GitHub issues associated with a specific project. Requires authentication.

```APIDOC
## GET /api/projects/:id/github/issues

### Description
Get GitHub issues linked to a project.

### Method
GET

### Endpoint
/api/projects/:id/github/issues

### Parameters
#### Path Parameters
- **id** (string) - Required - Project ID

### Response
#### Success Response (200 OK)
- **issues** (array) - A list of GitHub issues.
- **repoFullName** (string) - The full name of the repository (e.g., owner/repo).

### Response Example
```json
{
  "issues": [
    {
      "id": 12345,
      "number": 42,
      "title": "Issue Title",
      "state": "open",
      "htmlUrl": "https://github.com/owner/repo/issues/42",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "repoFullName": "owner/repo"
}
```

### Error Responses
- **400** - No linked repository
- **401** - GitHub authentication failed
- **404** - Project with id {id} not found
- **502** - GitHub API error
```

--------------------------------

### List and Run Command Sequences

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts/README.md

Use this script to list available command sequences or run a specific named sequence. Supports a dry-run option to preview actions. Sequences are defined in `scripts/sequences.config.json`.

```bash
node scripts/run-sequence.mjs list
node scripts/run-sequence.mjs run <name> [--dry-run]
npm run sequence -- list
npm run sequence -- run <name> [--dry-run]
```

--------------------------------

### Get Agent Task Status

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieve the current status of an agent task. This endpoint can be used for polling if real-time updates are not available.

```APIDOC
## GET /api/agent-tasks/:id/status

### Description
Get current agent task status (polling fallback).

### Method
GET

### Endpoint
/api/agent-tasks/:id/status

### Parameters
#### Path Parameters
- **id** (string) - Required - Agent Task ID

### Response
#### Success Response (200 OK)
- **status** (object or null) - The current status of the task, or null if no real-time status is available.
  - **taskId** (string) - The ID of the task.
  - **phase** (string) - The current phase of the task.
  - **progress** (integer) - The completion progress.
  - **message** (string) - The status message.
  - **updatedAt** (string) - Timestamp when the status was last updated.

#### Response Example
```json
{
  "status": {
    "taskId": "task-123",
    "phase": "running",
    "progress": 50,
    "message": "Processing files...",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

Returns `{ "status": null }` if no real-time status is available.
```

--------------------------------

### Synthesize all stacks for dev

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/cdk/platform-cdk/README.md

Run this command to synthesize all stacks for the development environment.

```bash
npm -w @cdk/platform-cdk run cdk:synth:dev
```

--------------------------------

### Get Agent Task by ID

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieve details of an agent task using its unique ID. This is useful for polling the status of a task.

```APIDOC
## GET /api/agent-tasks/:id

### Description
Get an agent task by ID.

### Method
GET

### Endpoint
/api/agent-tasks/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Agent Task ID

### Response
#### Success Response (200 OK)
- **task** (object) - Details of the agent task.
  - **id** (string) - Task ID.
  - **specGroupId** (string) - The ID of the spec group.
  - **action** (string) - The action performed by the task.
  - **status** (string) - The current status of the task (e.g., `RUNNING`).
  - **webhookUrl** (string) - The URL to send task updates to.
  - **context** (object) - Additional context for the task.
  - **createdAt** (string) - Timestamp when the task was created.
  - **updatedAt** (string) - Timestamp when the task was last updated.

#### Response Example
```json
{
  "task": {
    "id": "task-123",
    "specGroupId": "sg-123",
    "action": "implement",
    "status": "RUNNING",
    "webhookUrl": "https://agent-endpoint.example.com",
    "context": {
      "specGroupId": "sg-123",
      "specGroupName": "Feature Spec",
      "triggeredBy": "system",
      "triggeredAt": "2024-01-15T10:30:00.000Z"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

### Error Responses
- **404** - Agent task not found.
```

--------------------------------

### Run Tests

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/admin-portal/README.md

Execute Vitest unit and component tests.

```bash
npm -w client-website run test
```

--------------------------------

### Get User by Identifier API Endpoint

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/README.md

Fetches a user by their ID or email. Returns a 404 status code if the user is not found.

```http
GET /user/:identifier
```

--------------------------------

### Export Client website stack outputs for dev

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/cdk/platform-cdk/README.md

Use this command to export the outputs of the Client website stack for the development environment.

```bash
npm -w @cdk/platform-cdk run cdk:output:dev client-website-stack
```

--------------------------------

### GET /api/agent-tasks/:id/logs

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Fetches chronologically ordered log entries for a specific agent task from DynamoDB. Logs are retained for 30 days.

```APIDOC
## GET /api/agent-tasks/:id/logs — Fetch agent task logs

### Description
Retrieves chronologically ordered log entries for a task from DynamoDB. Logs have a 30-day TTL.

### Method
GET

### Endpoint
`/api/agent-tasks/:id/logs`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the agent task.

### Response
#### Success Response (200 OK)
- **taskId** (string) - The ID of the task.
- **logs** (array) - An array of log entries.
  - **level** (string) - The log level (e.g., `info`, `warn`, `error`).
  - **message** (string) - The log message.
  - **timestamp** (string) - The ISO 8601 timestamp of the log entry.
  - **metadata** (object) - Optional - Additional metadata associated with the log entry.

### Response Example
```json
{
  "taskId": "task-a1b2c3d4",
  "logs": [
    { "level": "info",  "message": "Task started",                      "timestamp": "2024-01-15T10:30:00.000Z" },
    { "level": "info",  "message": "Completed handler generation",       "timestamp": "2024-01-15T10:31:05.000Z" },
    { "level": "warn",  "message": "Retry on DynamoDB write (attempt 2)","timestamp": "2024-01-15T10:31:08.000Z" },
    { "level": "error", "message": "Spec validation failed",             "timestamp": "2024-01-15T10:31:10.000Z",
      "metadata": { "field": "handlers[0].route", "reason": "missing" }
    }
  ]
}
```
```

--------------------------------

### Get GitHub Pull Requests Linked to Project

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieves a list of GitHub pull requests associated with a specific project. Requires authentication.

```APIDOC
## GET /api/projects/:id/github/pulls

### Description
Get GitHub pull requests linked to a project.

### Method
GET

### Endpoint
/api/projects/:id/github/pulls

### Parameters
#### Path Parameters
- **id** (string) - Required - Project ID

### Response
#### Success Response (200 OK)
- **pullRequests** (array) - A list of GitHub pull requests.
- **repoFullName** (string) - The full name of the repository (e.g., owner/repo).

### Response Example
```json
{
  "pullRequests": [
    {
      "id": 12345,
      "number": 42,
      "title": "PR Title",
      "state": "open",
      "draft": false,
      "htmlUrl": "https://github.com/owner/repo/pull/42",
      "ciStatus": "passing",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "repoFullName": "owner/repo"
}
```

### Error Responses
- **400** - No linked repository
- **401** - GitHub authentication failed
- **404** - Project with id {id} not found
- **502** - GitHub API error
```

--------------------------------

### Validation Error Response

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Example of a JSON response for a 400 Bad Request due to validation failure. Indicates specific fields that are missing or invalid.

```json
{
  "error": "Validation error: password is required"
}
```

--------------------------------

### Build Project

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/admin-portal/README.md

Build the project for production. This command first runs `tsc -b` for TypeScript compilation and then `next build`.

```bash
npm -w client-website run build
```

--------------------------------

### GET /api/agent-tasks/:id/status

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Retrieves the latest persisted real-time status for a given agent task. This serves as a fallback mechanism when WebSocket connections are unavailable.

```APIDOC
## GET /api/agent-tasks/:id/status — Poll agent task status (fallback)

### Description
Retrieves the latest persisted real-time status for a task. Used as a polling fallback when WebSocket is unavailable. Returns `{ "status": null }` if no status has been recorded yet.

### Method
GET

### Endpoint
`/api/agent-tasks/:id/status`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the agent task.

### Response
#### Success Response (200 OK)
- **status** (object | null) - An object containing the task's status, or null if no status has been recorded.
  - **taskId** (string) - The ID of the task.
  - **phase** (string) - The current phase of the task.
  - **progress** (integer) - The completion progress.
  - **message** (string) - A human-readable message describing the current status.
  - **updatedAt** (string) - The ISO 8601 timestamp of the last status update.

### Response Example (Status Recorded)
```json
{
  "status": {
    "taskId": "task-a1b2c3d4",
    "phase": "running",
    "progress": 65,
    "message": "Processing spec group files (65%)...",
    "updatedAt": "2024-01-15T10:31:00.000Z"
  }
}
```

### Response Example (No Status Recorded)
```json
{
  "status": null
}
```
```

--------------------------------

### Run Linting and Fixes

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/admin-portal/README.md

Perform ESLint and Stylelint checks. Use `lint:fix` to automatically apply fixes.

```bash
npm -w client-website run lint
```

```bash
npm -w client-website run lint:fix
```

--------------------------------

### GET /api/spec-groups/:id

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Returns a spec group along with its UI state configuration and available state transitions. Requires a valid `dashboard_session` cookie.

```APIDOC
## GET /api/spec-groups/:id — Get spec group with state machine info

### Description
Returns the spec group, its UI state display config (label + colour badge), and all available state transitions with enabled/disabled status based on preconditions.

### Method
GET

### Endpoint
/api/spec-groups/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the spec group.

#### Cookies
- **dashboard_session** (string) - Required - The session cookie for authentication.

### Response
#### Success Response (200)
- **specGroup** (object) - The spec group details.
  - **id** (string) - Unique identifier for the spec group.
  - **name** (string) - The name of the spec group.
  - **state** (string) - The current state of the spec group.
  - **uiState** (object) - UI configuration for the spec group's state.
    - **label** (string) - Display label for the state.
    - **color** (string) - Color associated with the state.
  - **transitions** (array) - Available state transitions.
    - **name** (string) - The name of the transition.
    - **enabled** (boolean) - Whether the transition is currently enabled.
    - **preconditions** (array) - Conditions that must be met for the transition to be enabled.

### Response Example
(Example response structure not provided in source, but would typically include spec group details and transition information.)
```

--------------------------------

### Build Server for CDK Asset Staging

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/README.md

Builds the server application, ensuring the LAMBDA=true environment variable is set. This is part of the CDK asset staging process.

```bash
npm -w node-server run build
```

--------------------------------

### Get Spec Group by ID

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieves a specific spec group by its ID, including its current state information and available state transitions. Requires authentication.

```APIDOC
## GET /api/spec-groups/:id

### Description
Get a spec group by ID with state display info and available transitions.

### Method
GET

### Endpoint
/api/spec-groups/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Spec Group ID

### Response
#### Success Response (200 OK)
- **specGroup** (object) - Details of the spec group.
- **stateDisplay** (object) - Information for displaying the current state.
- **availableTransitions** (array) - List of possible state transitions.

### Response Example
```json
{
  "specGroup": {
    "id": "sg-123",
    "name": "Feature Spec",
    "state": "DRAFT",
    "sectionsCompleted": false,
    "allGatesPassed": false,
    "prMerged": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "stateDisplay": {
    "label": "Draft",
    "color": "gray"
  },
  "availableTransitions": [
    {
      "toState": "REVIEWED",
      "description": "Mark as reviewed",
      "enabled": true
    },
    {
      "toState": "APPROVED",
      "description": "Approve spec",
      "enabled": false,
      "disabledReason": "Must be reviewed first"
    }
  ]
}
```

### Error Responses
- **404** - Spec group with id {id} not found
```

--------------------------------

### Copy Assets for CDK

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/README.md

Prepares artifacts for the CDK, copying the built server and static client site into the CDK package's distribution directory. This produces `lambda.zip` and staged lambdas.

```bash
npm -w @cdk/platform-cdk run copy-assets-for-cdk
```

--------------------------------

### Run Test Suite

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/README.md

Executes the Vitest test suite, including unit and integration tests.

```bash
npm -w node-server run test
```

--------------------------------

### Get Spec Group by ID

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieves a spec group by its ID, including state display information and available transitions. Requires session cookie authentication.

```json
{
  "specGroup": {
    "id": "sg-123",
    "name": "Feature Spec",
    "state": "DRAFT",
    "sectionsCompleted": false,
    "allGatesPassed": false,
    "prMerged": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "stateDisplay": {
    "label": "Draft",
    "color": "gray"
  },
  "availableTransitions": [
    {
      "toState": "REVIEWED",
      "description": "Mark as reviewed",
      "enabled": true
    },
    {
      "toState": "APPROVED",
      "description": "Approve spec",
      "enabled": false,
      "disabledReason": "Must be reviewed first"
    }
  ]
}
```

--------------------------------

### Build All Monorepo Packages

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/README.md

Builds all packages and applications within the monorepo. This command should be run after making changes to ensure all components are up-to-date.

```bash
npm run build
```

--------------------------------

### Scaffold Repository Service Workflow

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Generates a skeleton workflow for a new repository service based on an entity slug. Supports optional scaffolding bundles and dry-run/force flags.

```bash
node scripts/create-repository-service.mjs <entity-slug>
# Optional flags:
#   --with handler           Include optional scaffolding bundles (comma separated or "all")
#   --dry-run  Preview generated files without writing
#   --force    Overwrite existing files created in a previous run
```

--------------------------------

### Deploy Infrastructure Sequence

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

A dedicated sequence for deploying the infrastructure stacks. It uses the CDK orchestrator with auto-approval enabled.

```bash
node scripts/cdk.mjs deploy infra --auto-approve
```

--------------------------------

### Get Agent Task Status (Polling Fallback)

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieve the current status of an agent task. This endpoint is intended as a fallback for polling if real-time updates are unavailable. Requires session authentication.

```json
{
  "status": {
    "taskId": "task-123",
    "phase": "running",
    "progress": 50,
    "message": "Processing files...",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

--------------------------------

### Scaffold Repository Service

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/README.md

Generates new repository service templates, including schema, CDK, and service files. Options include adding a handler, performing a dry run, or forcing the generation.

```bash
node scripts/create-repository-service.mjs <entity-slug> [--with handler] [--dry-run] [--force]
```

--------------------------------

### Get GitHub Issues for Project

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieves GitHub issues linked to a specific project. Requires session cookie authentication. Handles cases where no repository is linked or GitHub authentication fails.

```json
{
  "issues": [
    {
      "id": 12345,
      "number": 42,
      "title": "Issue Title",
      "state": "open",
      "htmlUrl": "https://github.com/owner/repo/issues/42",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "repoFullName": "owner/repo"
}
```

--------------------------------

### CDK Orchestrator Deploy All Stacks to Production

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Deploys all stacks to the production environment. The `--prod` flag targets production, and `--auto-approve` is required for non-interactive execution.

```bash
node scripts/cdk.mjs deploy all --prod --auto-approve
```

--------------------------------

### Run Test Suite with Coverage

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/README.md

Executes the Vitest test suite and collects code coverage.

```bash
npm -w node-server run test:coverage
```

--------------------------------

### Load Context for Agent Workflows

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/README.md

Loads the required context before making changes to agent workflows or Memory Bank. This script ensures consistency and prepares the environment.

```bash
node agents/scripts/load-context.mjs
```

--------------------------------

### Get GitHub Pull Requests for Project

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/node-server/docs/API.md

Retrieves GitHub pull requests linked to a specific project. Requires session cookie authentication. Handles various PR states and CI statuses.

```json
{
  "pullRequests": [
    {
      "id": 12345,
      "number": 42,
      "title": "PR Title",
      "state": "open",
      "draft": false,
      "htmlUrl": "https://github.com/owner/repo/pull/42",
      "ciStatus": "passing",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "repoFullName": "owner/repo"
}
```

--------------------------------

### Get Spec Group with State Machine Info (REST API)

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Retrieves a spec group along with its UI state configuration and available state transitions, indicating which are enabled or disabled based on preconditions. Requires a valid `dashboard_session` cookie.

```bash
curl http://localhost:3001/api/spec-groups/sg-ai-eng-dashboard-001 -b cookies.txt
```

--------------------------------

### Lint Project

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/apps/client-website/README.md

Perform ESLint and Stylelint checks on the project. Use `lint:fix` to automatically resolve fixable issues.

```bash
npm -w client-website run lint
```

```bash
npm -w client-website run lint:fix
```

```bash
npm -w client-website run lint:no-cache
```

--------------------------------

### Export API stack outputs for dev

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/cdk/platform-cdk/README.md

Use this command to export the outputs of the API stack for the development environment.

```bash
npm -w @cdk/platform-cdk run cdk:output:dev api-stack
```

--------------------------------

### List All Projects (REST API)

Source: https://context7.com/matthew-plusprogramming/monorepo/llms.txt

Retrieves a list of all projects, including their spec group counts and health indicators. Requires a valid `dashboard_session` cookie.

```bash
curl http://localhost:3001/api/projects -b cookies.txt

# Response 200 OK
{
  "projects": [
    {
      "id": "ai-eng-dashboard",
      "name": "Ai Eng Dashboard",
      "description": "Main dashboard project",
      "status": "active",
      "health": "green",
      "specGroupCount": 8,
      "specGroupSummary": {
        "total": 8,
        "byState": { "DRAFT": 2, "IN_PROGRESS": 3, "CONVERGED": 2, "MERGED": 1 },
        "allGatesPassed": 3,
        "criticalGatesFailed": 0
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}
# health: "green" | "yellow" | "red"
# status: "active" | "archived" | "draft"
```

--------------------------------

### CDK Orchestrator Deploy Infrastructure

Source: https://github.com/matthew-plusprogramming/monorepo/blob/main/scripts.md

Deploys specified infrastructure stacks or groups of stacks. Use `--auto-approve` to bypass interactive prompts, which is necessary for CI/CD environments.

```bash
node scripts/cdk.mjs deploy infra --auto-approve
```

```bash
node scripts/cdk.mjs deploy infra --auto-approve
```