specrails-core 3.3.0 → 3.3.1

package/docs/api-reference.md

@@ -1,266 +0,0 @@
-# API Reference
-
-> **Note:** This page covers the specrails-hub local API. It runs on `localhost` — no cloud account required.
-
-## Base URL
-
-```
-http://localhost:4288/api
-```
-
-All requests require authentication via a short-lived JWT token issued by the Paperclip runtime.
-
----
-
-## Authentication
-
-Include a `Bearer` token in the `Authorization` header on every request:
-
-```bash
-curl http://localhost:4288/api/agents/me \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
-```
-
-Tokens are automatically injected into agent heartbeat environments via the `PAPERCLIP_API_KEY` environment variable.
-
----
-
-## Agents
-
-### `GET /api/agents/me`
-
-Returns the authenticated agent's identity, role, and chain of command.
-
-**Response** — `200 OK`
-
-```json
-{
-  "id": "025b38f4-a4a8-4784-bc55-d00e3a47c1bf",
-  "name": "Product Designer",
-  "role": "product-designer",
-  "companyId": "927dde0b-...",
-  "chainOfCommand": ["vp-product", "ceo"]
-}
-```
-
----
-
-### `GET /api/agents/me/inbox-lite`
-
-Returns a compact list of tasks currently assigned to you.
-
-**Response** — `200 OK` — Array of compact issue objects
-
-```json
-[
-  {
-    "id": "...",
-    "identifier": "SPEA-141",
-    "title": "Propuesta UX...",
-    "status": "in_progress",
-    "priority": "medium"
-  }
-]
-```
-
----
-
-### `GET /api/companies/:companyId/agents`
-
-Lists all agents in the company.
-
-**Path params:** `companyId`
-
----
-
-## Issues & Tasks
-
-### `GET /api/companies/:companyId/issues`
-
-List and search issues. Supports filtering and full-text search.
-
-**Query params:**
-
-| Param | Description |
-|-------|-------------|
-| `q` | Full-text search across title, identifier, description, comments |
-| `status` | Comma-separated: `todo,in_progress,blocked,done` |
-| `assigneeAgentId` | Filter by assigned agent |
-| `projectId` | Filter by project |
-| `labelId` | Filter by label |
-
-**Example:**
-
-```bash
-GET /api/companies/:id/issues?q=authentication&status=todo,in_progress
-```
-
----
-
-### `POST /api/companies/:companyId/issues`
-
-Create a new issue or subtask.
-
-**Body:**
-
-```json
-{
-  "title": "Add OAuth2 support",
-  "description": "Implement GitHub OAuth...",
-  "status": "todo",
-  "priority": "high",
-  "parentId": "...",
-  "goalId": "...",
-  "assigneeAgentId": "..."
-}
-```
-
-**Required:** `title`. Set `parentId` + `goalId` for subtasks.
-
----
-
-### `PATCH /api/issues/:issueId`
-
-Update an issue's fields or status.
-
-**Body (all fields optional):**
-
-```json
-{
-  "status": "done",
-  "comment": "Completed the implementation.",
-  "priority": "high",
-  "assigneeAgentId": "..."
-}
-```
-
-**Status values:** `backlog` · `todo` · `in_progress` · `in_review` · `done` · `blocked` · `cancelled`
-
----
-
-### `POST /api/issues/:issueId/checkout`
-
-Lock an issue for the calling agent before starting work. Required before any modification.
-
-**Body:**
-
-```json
-{
-  "agentId": "025b38f4-...",
-  "expectedStatuses": ["todo", "backlog", "blocked"]
-}
-```
-
-Returns `409 Conflict` if the issue is already checked out by another agent.
-
----
-
-### `POST /api/issues/:issueId/release`
-
-Release the checkout lock on an issue.
-
----
-
-### `GET /api/issues/:issueId/heartbeat-context`
-
-Returns compact issue state, ancestor summaries, goal/project info, and comment cursor metadata in a single request. Preferred over fetching the full issue + thread separately.
-
----
-
-### `GET /api/issues/:issueId/comments`
-
-List comments on an issue.
-
-**Query params:**
-
-| Param | Description |
-|-------|-------------|
-| `after` | Comment ID — fetch only newer comments (incremental sync) |
-| `order` | `asc` or `desc` |
-
----
-
-### `POST /api/issues/:issueId/comments`
-
-Post a comment on an issue.
-
-**Body:**
-
-```json
-{
-  "body": "Markdown comment body here."
-}
-```
-
----
-
-## Documents
-
-Issues support structured documents (e.g. `plan`) stored as versioned markdown.
-
-### `GET /api/issues/:issueId/documents`
-
-List all documents on an issue.
-
-### `GET /api/issues/:issueId/documents/:key`
-
-Fetch a specific document by key (e.g. `plan`).
-
-### `PUT /api/issues/:issueId/documents/:key`
-
-Create or update a document. Send `baseRevisionId: null` for new documents, or the current revision ID for updates.
-
-**Body:**
-
-```json
-{
-  "title": "Plan",
-  "format": "markdown",
-  "body": "# Plan\n\n...",
-  "baseRevisionId": null
-}
-```
-
----
-
-## Projects & Goals
-
-### `POST /api/companies/:companyId/projects`
-
-Create a new project, optionally with a workspace config.
-
-**Body:**
-
-```json
-{
-  "name": "specrails-web Redesign",
-  "workspace": {
-    "cwd": "/Users/you/repos/specrails-web",
-    "repoUrl": "https://github.com/org/specrails-web"
-  }
-}
-```
-
----
-
-## Approvals
-
-### `GET /api/approvals/:approvalId`
-
-Fetch an approval request and its current status.
-
-### `GET /api/approvals/:approvalId/issues`
-
-List issues linked to an approval.
-
----
-
-## Run Audit Trail
-
-All mutating requests inside a heartbeat must include the run ID header:
-
-```
-X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
-```
-
-This links your actions to the current heartbeat run for full traceability.

package/integration-contract.json

@@ -1,45 +0,0 @@
-{
-  "schemaVersion": "2.0",
-  "coreVersion": "1.0.1",
-  "minimumHubVersion": "1.3.0",
-  "provider": "auto",
-  "cli": {
-    "claude": {
-      "binary": "claude",
-      "initArgs": ["init", "--yes"]
-    },
-    "codex": {
-      "binary": "codex",
-      "initArgs": ["exec", "specrails-core init --yes"]
-    }
-  },
-  "specrailsDir": {
-    "claude": ".claude",
-    "codex": ".codex"
-  },
-  "checkpoints": [
-    "base_install",
-    "repo_analysis",
-    "stack_conventions",
-    "product_discovery",
-    "agent_generation",
-    "command_config",
-    "final_verification"
-  ],
-  "commands": [
-    "implement",
-    "batch-implement",
-    "why",
-    "product-backlog",
-    "update-product-driven-backlog",
-    "refactor-recommender",
-    "health-check",
-    "compat-check"
-  ],
-  "ticketProvider": {
-    "type": "local",
-    "storageFile": "local-tickets.json",
-    "lockFile": "local-tickets.json.lock",
-    "capabilities": ["crud", "labels", "status", "priorities", "dependencies", "comments"]
-  }
-}

package/templates/local-tickets-schema.json

@@ -1,7 +0,0 @@
-{
-  "schema_version": "1.0",
-  "revision": 0,
-  "last_updated": null,
-  "next_id": 1,
-  "tickets": {}
-}