@hechura/noreaster-cli 0.1.1 → 0.2.2

package/dist/commands/docs.js

@@ -2,14 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDocumentCommands = registerDocumentCommands;
 const http_1 = require("../http");
+const document_templates_1 = require("../document-templates");
 function registerDocumentCommands(parent) {
     const docs = parent.command("docs").description("Manage documents");
+    docs
+        .command("template")
+        .description("Print the markdown template for a document type")
+        .argument("<docType>", "Document type (feature_description, design_spec, adr, ...)")
+        .action((docType) => {
+        const template = (0, document_templates_1.templateForDocType)(docType);
+        if (!template) {
+            console.error(`No template for doc type: ${docType}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(template);
+    });
     docs
         .command("list")
         .description("List documents")
         .option("--project-id <projectId>")
         .option("--customer-id <customerId>")
         .option("--prospect-id <prospectId>")
+        .option("--feature <featureId>")
+        .option("--type <docType>")
+        .option("--status <status>")
+        .option("--include-drafts", "Include non-approved documents")
         .option("--limit <limit>")
         .action(async (options) => {
         const params = new URLSearchParams();
@@ -19,6 +37,14 @@ function registerDocumentCommands(parent) {
             params.set("customer_id", options.customerId);
         if (options.prospectId)
             params.set("prospect_id", options.prospectId);
+        if (options.feature)
+            params.set("feature_id", options.feature);
+        if (options.type)
+            params.set("doc_type", options.type);
+        if (options.status)
+            params.set("status", options.status);
+        if (options.includeDrafts)
+            params.set("include_drafts", "true");
         if (options.limit)
             params.set("limit", options.limit);
         const query = params.toString();
@@ -29,8 +55,13 @@ function registerDocumentCommands(parent) {
         .command("get")
         .description("Get document by id")
         .argument("<id>")
-        .action(async (id) => {
-        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", `/api/agent/documents/${id}`);
+        .option("--include-drafts", "Include non-approved documents")
+        .action(async (id, options) => {
+        const params = new URLSearchParams();
+        if (options.includeDrafts)
+            params.set("include_drafts", "true");
+        const query = params.toString();
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", `/api/agent/documents/${id}${query ? `?${query}` : ""}`);
         console.log(JSON.stringify(result, null, 2));
     });
     docs
@@ -50,6 +81,36 @@ function registerDocumentCommands(parent) {
         const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "PATCH", `/api/agent/documents/${id}`, (0, http_1.parsePayload)(options.data));
         console.log(JSON.stringify(result, null, 2));
     });
+    docs
+        .command("transition")
+        .description("Transition document status")
+        .argument("<id>")
+        .requiredOption("--status <status>", "Target status")
+        .option("--summary <summary>", "Change summary")
+        .action(async (id, options) => {
+        const payload = { status: options.status };
+        if (options.summary)
+            payload.change_summary = options.summary;
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "PATCH", `/api/agent/documents/${id}`, payload);
+        console.log(JSON.stringify(result, null, 2));
+    });
+    docs
+        .command("revisions")
+        .description("List document revisions")
+        .argument("<id>")
+        .option("--include-drafts", "Include revisions for non-approved documents")
+        .option("--version <version>", "Fetch a specific revision version")
+        .action(async (id, options) => {
+        const params = new URLSearchParams();
+        if (options.includeDrafts)
+            params.set("include_drafts", "true");
+        const query = params.toString();
+        const path = options.version
+            ? `/api/agent/documents/${id}/revisions/${options.version}`
+            : `/api/agent/documents/${id}/revisions`;
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", `${path}${query ? `?${query}` : ""}`);
+        console.log(JSON.stringify(result, null, 2));
+    });
     docs
         .command("delete")
         .description("Delete document")

package/dist/commands/draft-runs.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDraftRunCommands = registerDraftRunCommands;
+const http_1 = require("../http");
+function registerDraftRunCommands(parent) {
+    const draftRuns = parent.command("draft-runs").description("Manage external draft work-item runs");
+    draftRuns
+        .command("list")
+        .description("List draft runs for a feature")
+        .argument("<featureId>")
+        .action(async (featureId) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", `/api/agent/features/${featureId}/draft-runs`);
+        console.log(JSON.stringify(result, null, 2));
+    });
+    draftRuns
+        .command("get")
+        .description("Get a draft run")
+        .argument("<featureId>")
+        .argument("<runId>")
+        .action(async (featureId, runId) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", `/api/agent/features/${featureId}/draft-runs/${runId}`);
+        console.log(JSON.stringify(result, null, 2));
+    });
+    draftRuns
+        .command("submit")
+        .description("Submit a draft run for a feature")
+        .argument("<featureId>")
+        .requiredOption("--data <json>", "JSON payload with source_document_id and items")
+        .action(async (featureId, options) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "POST", `/api/agent/features/${featureId}/draft-runs`, (0, http_1.parsePayload)(options.data));
+        console.log(JSON.stringify(result, null, 2));
+    });
+    draftRuns
+        .command("apply")
+        .description("Apply a draft run (creates work items)")
+        .argument("<featureId>")
+        .argument("<runId>")
+        .option("--data <json>", "Optional edited items payload")
+        .action(async (featureId, runId, options) => {
+        const payload = options.data ? (0, http_1.parsePayload)(options.data) : {};
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "POST", `/api/agent/features/${featureId}/draft-runs/${runId}/apply`, payload);
+        console.log(JSON.stringify(result, null, 2));
+    });
+}

package/dist/commands/features.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeatureCommands = registerFeatureCommands;
+const http_1 = require("../http");
+function registerFeatureCommands(parent) {
+    const features = parent.command("features").description("Manage features");
+    features
+        .command("list")
+        .description("List features")
+        .option("--project-id <projectId>")
+        .option("--status <status>")
+        .option("--limit <limit>")
+        .action(async (options) => {
+        const params = new URLSearchParams();
+        if (options.projectId)
+            params.set("project_id", options.projectId);
+        if (options.status)
+            params.set("status", options.status);
+        if (options.limit)
+            params.set("limit", options.limit);
+        const query = params.toString();
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", `/api/agent/features${query ? `?${query}` : ""}`);
+        console.log(JSON.stringify(result, null, 2));
+    });
+    features
+        .command("get")
+        .description("Get feature by id")
+        .argument("<id>")
+        .action(async (id) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", `/api/agent/features/${id}`);
+        console.log(JSON.stringify(result, null, 2));
+    });
+    features
+        .command("create")
+        .description("Create feature")
+        .requiredOption("--data <json>", "JSON payload")
+        .action(async (options) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "POST", "/api/agent/features", (0, http_1.parsePayload)(options.data));
+        console.log(JSON.stringify(result, null, 2));
+    });
+    features
+        .command("update")
+        .description("Update feature")
+        .argument("<id>")
+        .requiredOption("--data <json>", "JSON payload")
+        .action(async (id, options) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "PATCH", `/api/agent/features/${id}`, (0, http_1.parsePayload)(options.data));
+        console.log(JSON.stringify(result, null, 2));
+    });
+    features
+        .command("transition")
+        .description("Transition feature status")
+        .argument("<id>")
+        .requiredOption("--status <status>", "Target status")
+        .action(async (id, options) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "PATCH", `/api/agent/features/${id}`, { status: options.status });
+        console.log(JSON.stringify(result, null, 2));
+    });
+    features
+        .command("delete")
+        .description("Delete feature")
+        .argument("<id>")
+        .action(async (id) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "DELETE", `/api/agent/features/${id}`);
+        console.log(JSON.stringify(result, null, 2));
+    });
+}

package/dist/commands/my-work.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMyWorkCommands = registerMyWorkCommands;
+const http_1 = require("../http");
+function registerMyWorkCommands(parent) {
+    parent
+        .command("my-work")
+        .description("Discover assigned work items, pending reviews, open gates, and draft runs")
+        .action(async () => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", "/api/agent/my-work");
+        console.log(JSON.stringify(result, null, 2));
+    });
+}

package/dist/commands/reviews.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerReviewCommands = registerReviewCommands;
+const http_1 = require("../http");
+function registerReviewCommands(parent) {
+    const reviews = parent.command("reviews").description("Manage document reviews");
+    reviews
+        .command("list")
+        .description("List reviews for a document")
+        .argument("<documentId>")
+        .action(async (documentId) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "GET", `/api/agent/documents/${documentId}/reviews`);
+        console.log(JSON.stringify(result, null, 2));
+    });
+    reviews
+        .command("request")
+        .description("Request a review on a document")
+        .argument("<documentId>")
+        .option("--data <json>", "JSON payload with reviewers")
+        .action(async (documentId, options) => {
+        const payload = options.data ? (0, http_1.parsePayload)(options.data) : {};
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "POST", `/api/agent/documents/${documentId}/reviews`, payload);
+        console.log(JSON.stringify(result, null, 2));
+    });
+    reviews
+        .command("approve")
+        .description("Approve a review")
+        .argument("<documentId>")
+        .argument("<reviewId>")
+        .action(async (documentId, reviewId) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "PATCH", `/api/agent/documents/${documentId}/reviews/${reviewId}`, { action: "approve" });
+        console.log(JSON.stringify(result, null, 2));
+    });
+    reviews
+        .command("request-changes")
+        .description("Request changes on a review")
+        .argument("<documentId>")
+        .argument("<reviewId>")
+        .action(async (documentId, reviewId) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "PATCH", `/api/agent/documents/${documentId}/reviews/${reviewId}`, { action: "request_changes" });
+        console.log(JSON.stringify(result, null, 2));
+    });
+    reviews
+        .command("check")
+        .description("Tick a checklist item")
+        .argument("<documentId>")
+        .argument("<reviewId>")
+        .argument("<itemKey>")
+        .option("--unchecked", "Mark item unchecked")
+        .action(async (documentId, reviewId, itemKey, options) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "PATCH", `/api/agent/documents/${documentId}/reviews/${reviewId}`, { action: "check", item_key: itemKey, checked: !options.unchecked });
+        console.log(JSON.stringify(result, null, 2));
+    });
+    reviews
+        .command("comment")
+        .description("Add a comment to a document")
+        .argument("<documentId>")
+        .requiredOption("--body <text>", "Comment body")
+        .option("--review-id <reviewId>")
+        .action(async (documentId, options) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "POST", `/api/agent/documents/${documentId}/comments`, { body: options.body, review_id: options.reviewId ?? null });
+        console.log(JSON.stringify(result, null, 2));
+    });
+    reviews
+        .command("resolve-comment")
+        .description("Resolve a comment")
+        .argument("<documentId>")
+        .argument("<commentId>")
+        .action(async (documentId, commentId) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "PATCH", `/api/agent/documents/${documentId}/comments/${commentId}`, { action: "resolve" });
+        console.log(JSON.stringify(result, null, 2));
+    });
+}

package/dist/commands/skill.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSkillCommands = registerSkillCommands;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+function resolvePackagedSkillPath() {
+    const candidates = [
+        (0, node_path_1.join)(__dirname, "../../skills/hechura-manager-noreaster/SKILL.md"),
+        (0, node_path_1.join)(__dirname, "../../../.agents/skills/hechura-manager-noreaster/SKILL.md"),
+        (0, node_path_1.join)(process.cwd(), "packages/noreaster-cli/skills/hechura-manager-noreaster/SKILL.md"),
+        (0, node_path_1.join)(process.cwd(), ".agents/skills/hechura-manager-noreaster/SKILL.md"),
+    ];
+    for (const candidate of candidates) {
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    throw new Error("Packaged skill file not found");
+}
+function installTargets() {
+    const home = (0, node_os_1.homedir)();
+    return [
+        (0, node_path_1.join)(home, ".claude/skills/hechura-manager-noreaster/SKILL.md"),
+        (0, node_path_1.join)(home, ".cursor/skills/hechura-manager-noreaster/SKILL.md"),
+    ];
+}
+function registerSkillCommands(parent) {
+    const skill = parent.command("skill").description("Manage the Noreaster agent skill");
+    skill
+        .command("install")
+        .description("Copy the packaged hechura-manager-noreaster skill into local skill directories")
+        .action(() => {
+        const source = resolvePackagedSkillPath();
+        const installed = [];
+        for (const target of installTargets()) {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+            (0, node_fs_1.copyFileSync)(source, target);
+            installed.push(target);
+        }
+        console.log(JSON.stringify({
+            data: {
+                source,
+                installed,
+            },
+        }, null, 2));
+    });
+}

package/dist/commands/tasks.js

@@ -9,6 +9,7 @@ function registerTaskCommands(parent) {
         .description("List tasks")
         .option("--project-id <projectId>")
         .option("--status <status>")
+        .option("--area <area>", "Filter by project area key")
         .option("--limit <limit>")
         .action(async (options) => {
         const params = new URLSearchParams();
@@ -16,6 +17,8 @@ function registerTaskCommands(parent) {
             params.set("project_id", options.projectId);
         if (options.status)
             params.set("status", options.status);
+        if (options.area)
+            params.set("area", options.area);
         if (options.limit)
             params.set("limit", options.limit);
         const query = params.toString();
@@ -55,4 +58,25 @@ function registerTaskCommands(parent) {
         const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "DELETE", `/api/agent/tasks/${id}`);
         console.log(JSON.stringify(result, null, 2));
     });
+    tasks
+        .command("pr-link")
+        .description("Link a GitHub pull request URL to a task")
+        .argument("<id>")
+        .requiredOption("--url <url>", "GitHub pull request URL")
+        .action(async (id, options) => {
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "POST", `/api/agent/tasks/${id}/pull-requests`, {
+            url: options.url,
+        });
+        console.log(JSON.stringify(result, null, 2));
+    });
+    tasks
+        .command("pr-unlink")
+        .description("Unlink a GitHub pull request URL from a task")
+        .argument("<id>")
+        .requiredOption("--url <url>", "GitHub pull request URL")
+        .action(async (id, options) => {
+        const params = new URLSearchParams({ url: options.url });
+        const result = await (0, http_1.apiRequest)((0, http_1.resolveConfig)(), "DELETE", `/api/agent/tasks/${id}/pull-requests?${params.toString()}`);
+        console.log(JSON.stringify(result, null, 2));
+    });
 }

package/dist/document-templates.js

@@ -0,0 +1,468 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEMPLATE_DOC_TYPES = void 0;
+exports.isTemplateDocType = isTemplateDocType;
+exports.templateForDocType = templateForDocType;
+exports.resolveDocumentContent = resolveDocumentContent;
+exports.TEMPLATE_DOC_TYPES = [
+    "feature_description",
+    "design_spec",
+    "adr",
+    "architecture",
+    "design_system",
+    "implementation_plan",
+    "prd",
+    "technical_design",
+    "feature_summary",
+    "sprint_plan",
+    "executive_summary",
+];
+const AI_WRITING_HINT = `<!-- Writing for AI tools:
+     - Be explicit with exact values ("max file size: 10MB", not "reasonable").
+     - Describe UI in words — AI tools cannot parse Figma links.
+     - Edge-case table rows become test cases; be exhaustive.
+     - Include API request/response shapes so handlers can be generated directly.
+-->`;
+const FEATURE_DESCRIPTION_TEMPLATE = `# Feature Description
+
+${AI_WRITING_HINT}
+
+## Problem Statement
+
+<!-- 2-3 sentences describing the user or business problem this feature solves.
+     Be specific about who is affected and what pain they experience. -->
+
+## Goals & Success Metrics
+
+| Goal | Success Metric | Baseline | Target |
+|------|---------------|----------|--------|
+| | | | |
+
+## User Stories
+
+- As a [persona], I want to [action] so that [outcome].
+
+## Requirements
+
+### Functional Requirements
+
+1. The system must [specific behavior].
+2. When a user [action], the system must [specific response].
+
+### Non-Functional Requirements
+
+- **Performance:**
+- **Accessibility:**
+- **Security:**
+- **Scalability:**
+
+## Scope
+
+### In Scope
+
+-
+
+### Out of Scope
+
+-
+
+## UX / Design
+
+**Design Link:**
+
+### Key Screens & Flows
+
+**Screen: [Name]**
+- Layout:
+- Primary action:
+- Feedback states:
+
+**Flow: [Name]**
+1. User [action] → System shows [response]
+
+## Open Questions
+
+- [ ]
+`;
+const DESIGN_SPEC_TEMPLATE = `# Feature Design Spec
+
+${AI_WRITING_HINT}
+
+## Technical Context
+
+<!-- Co-authored with engineering after requirements approval. -->
+
+## Affected Areas
+
+<!-- One subsection per project area. Each developer walks their area to generate work items. -->
+
+### Frontend
+
+- Services & APIs Affected:
+- Changes needed:
+
+### Backend
+
+- Services & APIs Affected:
+- Changes needed:
+
+## API Contract
+
+\`\`\`
+POST /api/v1/[resource]
+Request:
+{
+  "field": "type — description"
+}
+
+Response (200):
+{
+  "field": "type — description"
+}
+
+Response (400):
+{
+  "error": "VALIDATION_ERROR",
+  "message": "Human-readable description"
+}
+\`\`\`
+
+## Data Model Changes
+
+\`\`\`
+Table: [table_name]
+  + new_column (type, constraints)
+  ~ modified_column (old_type → new_type)
+\`\`\`
+
+## Edge Cases & Error Handling
+
+| # | Scenario | Expected Behavior | Error Message (if applicable) |
+|---|----------|-------------------|-------------------------------|
+| 1 | | | |
+
+## Dependencies & Risks
+
+-
+
+## Open Questions
+
+- [ ]
+
+## Decision Log
+
+| Date | Decision | Rationale | Decided By |
+|------|----------|-----------|------------|
+| | | | |
+`;
+const ADR_TEMPLATE = `# ADR: [Title]
+
+${AI_WRITING_HINT}
+
+## Context
+
+<!-- What issue motivates this decision? Include constraints and forces. -->
+
+## Decision
+
+<!-- State the change clearly and concisely. -->
+
+## Consequences
+
+### Positive
+
+-
+
+### Negative
+
+-
+
+### Neutral
+
+-
+
+## Alternatives Considered
+
+### [Alternative 1]
+
+- **Description:**
+- **Rejected because:**
+
+### [Alternative 2]
+
+- **Description:**
+- **Rejected because:**
+`;
+const ARCHITECTURE_TEMPLATE = `# Architecture Overview
+
+${AI_WRITING_HINT}
+
+## Service Map
+
+<!-- List services and how they relate. -->
+
+-
+
+## Cross-Service Data Flows
+
+<!-- Describe the important flows that no single service owns. -->
+
+-
+
+## Shared Infrastructure
+
+<!-- Auth, storage, messaging, observability, etc. -->
+
+-
+
+## Conventions
+
+-
+`;
+const DESIGN_SYSTEM_TEMPLATE = `# Design System
+
+${AI_WRITING_HINT}
+
+## Tokens
+
+<!-- Colors, spacing, radii, elevation. Prefer exact values AI tools can apply. -->
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| | | |
+
+## Typography
+
+| Role | Font | Size / Line height | Weight |
+|------|------|--------------------|--------|
+| Display | | | |
+| Body | | | |
+| Caption | | | |
+
+## Components
+
+### [Component name]
+
+- Purpose:
+- Variants:
+- States (default / hover / focus / disabled / error):
+- Content rules:
+
+## Interaction Patterns
+
+- Navigation:
+- Forms & validation:
+- Feedback (toasts, empty states, loading):
+
+## Accessibility
+
+- Contrast:
+- Keyboard:
+- Screen reader / labels:
+- Motion:
+`;
+const IMPLEMENTATION_PLAN_TEMPLATE = `# Implementation Plan
+
+${AI_WRITING_HINT}
+
+## Plan
+
+<!-- Steps, sequencing, and ownership for this work item. -->
+
+1.
+
+## Risks & Dependencies
+
+-
+
+## Implementation Notes
+
+<!-- Fill in AFTER development, not before. -->
+
+### Deviations from Spec
+
+-
+
+### Key Implementation Details
+
+-
+
+### Known Limitations
+
+-
+`;
+const PRD_TEMPLATE = `# Product Requirements Document
+
+${AI_WRITING_HINT}
+
+## Problem
+
+## Goals
+
+## Personas
+
+## Feature List
+
+-
+`;
+const TECHNICAL_DESIGN_TEMPLATE = `# Technical Design
+
+${AI_WRITING_HINT}
+
+## Technical Context
+
+<!-- Co-authored with engineering. -->
+
+## Affected Areas
+
+<!-- One subsection per project area. -->
+
+### Frontend
+
+- Services & APIs Affected:
+- Changes needed:
+
+### Backend
+
+- Services & APIs Affected:
+- Changes needed:
+
+## API Contract
+
+\`\`\`
+POST /api/v1/[resource]
+Request:
+{
+  "field": "type — description"
+}
+
+Response (200):
+{
+  "field": "type — description"
+}
+
+Response (400):
+{
+  "error": "VALIDATION_ERROR",
+  "message": "Human-readable description"
+}
+\`\`\`
+
+## Data Model Changes
+
+\`\`\`
+Table: [table_name]
+  + new_column (type, constraints)
+  ~ modified_column (old_type → new_type)
+\`\`\`
+
+## Edge Cases & Error Handling
+
+| # | Scenario | Expected Behavior | Error Message (if applicable) |
+|---|----------|-------------------|-------------------------------|
+| 1 | | | |
+
+## Dependencies & Risks
+
+-
+
+## Open Questions
+
+- [ ]
+
+## Decision Log
+
+| Date | Decision | Rationale | Decided By |
+|------|----------|-----------|------------|
+| | | | |
+`;
+const FEATURE_SUMMARY_TEMPLATE = `# Feature Summary
+
+${AI_WRITING_HINT}
+
+## Problem
+
+## Outcome
+
+## In Scope
+
+-
+
+## Out of Scope
+
+-
+
+## Key Decisions
+
+-
+`;
+const SPRINT_PLAN_TEMPLATE = `# Sprint Plan
+
+${AI_WRITING_HINT}
+
+## Sprint Goal
+
+## Scope
+
+-
+
+## Deliverables
+
+| Item | Owner | Done when |
+|------|-------|-----------|
+| | | |
+
+## Risks & Dependencies
+
+-
+
+## Notes
+
+-
+`;
+const EXECUTIVE_SUMMARY_TEMPLATE = `# Executive Summary
+
+${AI_WRITING_HINT}
+
+## Situation
+
+## Recommendation
+
+## Status
+
+## Decisions Needed
+
+-
+
+## Next Steps
+
+-
+`;
+const TEMPLATES = {
+    feature_description: FEATURE_DESCRIPTION_TEMPLATE,
+    design_spec: DESIGN_SPEC_TEMPLATE,
+    adr: ADR_TEMPLATE,
+    architecture: ARCHITECTURE_TEMPLATE,
+    design_system: DESIGN_SYSTEM_TEMPLATE,
+    implementation_plan: IMPLEMENTATION_PLAN_TEMPLATE,
+    prd: PRD_TEMPLATE,
+    technical_design: TECHNICAL_DESIGN_TEMPLATE,
+    feature_summary: FEATURE_SUMMARY_TEMPLATE,
+    sprint_plan: SPRINT_PLAN_TEMPLATE,
+    executive_summary: EXECUTIVE_SUMMARY_TEMPLATE,
+};
+function isTemplateDocType(value) {
+    return value != null && exports.TEMPLATE_DOC_TYPES.includes(value);
+}
+function templateForDocType(docType) {
+    if (!isTemplateDocType(docType))
+        return null;
+    return TEMPLATES[docType];
+}
+/** Seed template content when creating a doc with empty content. Explicit content always wins. */
+function resolveDocumentContent(docType, content) {
+    if (content != null && content.trim().length > 0) {
+        return content;
+    }
+    return templateForDocType(docType);
+}

package/dist/index.js

@@ -13,13 +13,23 @@ const customers_1 = require("./commands/customers");
 const prospects_1 = require("./commands/prospects");
 const meetings_1 = require("./commands/meetings");
 const timeline_1 = require("./commands/timeline");
+const features_1 = require("./commands/features");
+const reviews_1 = require("./commands/reviews");
+const draft_runs_1 = require("./commands/draft-runs");
+const my_work_1 = require("./commands/my-work");
+const skill_1 = require("./commands/skill");
 async function main() {
     const program = new commander_1.Command()
         .name("noreaster")
         .description("CLI for admin-equivalent AI agent API access")
-        .version("0.1.0");
+        .version("0.1.1");
     (0, tasks_1.registerTaskCommands)(program);
     (0, docs_1.registerDocumentCommands)(program);
+    (0, features_1.registerFeatureCommands)(program);
+    (0, reviews_1.registerReviewCommands)(program);
+    (0, draft_runs_1.registerDraftRunCommands)(program);
+    (0, my_work_1.registerMyWorkCommands)(program);
+    (0, skill_1.registerSkillCommands)(program);
     (0, projects_1.registerProjectCommands)(program);
     (0, team_1.registerTeamCommands)(program);
     (0, messages_1.registerMessageCommands)(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hechura/noreaster-cli",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "description": "CLI for Hechura Noreaster agent API access",
   "repository": {
     "type": "git",
@@ -11,17 +11,19 @@
     "access": "public"
   },
   "bin": {
-    "noreaster": "./dist/index.js",
-    "hechura-agent": "./dist/index.js"
+    "noreaster": "dist/index.js",
+    "hechura-agent": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
-    "build": "npx tsc -p tsconfig.json",
+    "build": "npx tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "prepack": "npm run clean && npm run build",
-    "pack:dry-run": "npm pack --dry-run"
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:package": "npm publish --access public"
   },
   "engines": {
     "node": ">=18"
@@ -30,6 +32,7 @@
     "commander": "^14.0.3"
   },
   "devDependencies": {
+    "@types/node": "^22.20.1",
     "typescript": "^5.7.3"
   }
 }

package/skills/hechura-manager-noreaster/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: hechura-manager-noreaster
+description: Operates Hechura Manager / Noreaster via the official agent CLI and PAT-scoped APIs, including the feature-spec process chain. Use when the user asks to manage Noreaster projects, tasks, sprints, customers, prospects, meetings, timeline entries, documents, features, reviews, draft runs, PR links, team/admin agent routes, or references HECHURA_AGENT_TOKEN, agent scopes, or noreaster.vercel.app docs. Also trigger for process phrases like "pick up my next work item", "submit the breakdown for review", "what gates are open", "link this PR", or "install the noreaster skill".
+---
+
+# Hechura Manager / Noreaster Operations
+
+Use this skill for operational work in Noreaster through the official agent CLI surface.
+
+## Execution Defaults
+
+1. Prefer the published CLI:
+   - `npx @hechura/noreaster-cli@0.2.2 <command>` or `noreaster <command>` after global install (`npm install -g @hechura/noreaster-cli@0.2.2`)
+   - In this repo: `npm run agent -- <command>`
+2. Default API base URL:
+   - `https://noreaster.vercel.app`
+3. Required runtime credentials:
+   - `HECHURA_API_BASE_URL`
+   - `HECHURA_AGENT_TOKEN`
+4. Before any write/delete operation, preview with a list/get command first.
+5. Never run delete/destructive commands without explicit user confirmation.
+6. After upgrading the CLI, always run `noreaster skill install` so local skill copies stay current.
+
+## Spec Process Chain
+
+Noreaster is the system of record. External agents (or humans) drive generation and transitions. Chain:
+
+```
+PRD → Feature → Feature PRD (feature_description) → Feature Spec (design_spec)
+→ Work Items → Implementation Plan docs → GitHub PRs
+```
+
+### The source-of-truth document set
+
+Project documents are the versioned source of truth for how a project is built. Read the relevant docs before doing work; treat their contents as binding unless a human approves a change. UI labels are for humans; CLI/API payloads use `doc_type` values:
+
+| UI label | `doc_type` | Purpose — how agents use it |
+| --- | --- | --- |
+| PRD | `prd` | Product requirements: problem, goals, personas, feature list. Governs *what* to build and why. |
+| Architecture | `architecture` | System overview: services, data flows, infrastructure. Governs *where* code lives and how systems connect. |
+| Technical Design | `technical_design` | Project-level technical design: affected areas, API contracts, data model, edge cases. Governs implementation shape. |
+| Design System | `design_system` | UI system: tokens, typography, components, a11y rules. All UI work must conform to it. |
+| Feature Summary | `feature_summary` | Concise feature overview: problem, outcome, in/out of scope. Orients agents before deeper docs. |
+| Sprint Plan | `sprint_plan` | Sprint goal, scope, deliverables, risks. Governs what belongs in the current sprint. |
+| Executive Summary | `executive_summary` | Stakeholder-facing status and decisions. Read for context; humans own the framing. |
+| General Context | `general_context` | Background context for the project or engagement. Read early; useful constraints often live here. |
+| Feature PRD | `feature_description` | Feature-scoped requirements (feature-linked, not a Core Document). |
+| Feature Spec | `design_spec` | Feature-scoped technical design (feature-linked, not a Core Document). |
+
+Do not invent types like `feature_prd`. Use the `doc_type` column in create/update payloads and `docs template <docType>`.
+
+Ownership defaults:
+
+- PRD / Feature / Feature PRD: PM-owned
+- Feature Spec: engineering-owned
+- Work-item breakdowns: submitted by external agents as draft runs; humans review/apply
+- Implementation plans: authored by a developer's agent, linked to a work item
+- PRs: linked manually or via inbound webhook matching `{ticket_prefix}-<n>` (e.g. `AIM-12`)
+
+## Lifecycle Gates
+
+Illegal transitions are refused server-side with HTTP 409 and `gate_not_satisfied`.
+
+Common gates:
+
+- Feature PRD (`feature_description`) must be approved before Feature Spec (`design_spec`) can be approved
+- Feature Spec must be approved before draft-run apply creates work items
+- Document → `approved` requires a matching approved review
+- Agent document reads return `approved` docs by default; use `--include-drafts` only when intentionally working on drafts
+
+When refused, read the `gate` / `error` fields, fix the missing prerequisite, then retry.
+
+## Consuming project documents
+
+Before implementing a work item, load the governing docs — do not invent contracts from memory.
+
+1. Fetch the work item: `tasks get <id>`
+2. Follow `source_document_id` (or the feature's Feature Spec / `design_spec`) and read it: `docs get <id>`
+3. Load project foundation docs:
+   - `docs list --project-id <id> --type architecture`
+   - `docs list --project-id <id> --type design_system`
+   - `docs list --project-id <id> --type technical_design`
+   - `docs list --project-id <id> --type general_context` (constraints and background often live here)
+4. If an ADR governs the change, read it (`--type adr`) before contradicting prior decisions.
+
+Compliance rules while coding:
+
+- Honor the Feature Spec's API contract and data model verbatim
+- Every edge-case table row becomes a required test
+- UI work must conform to the approved design-system doc (tokens, components, a11y)
+- Do not contradict an approved ADR — propose a new ADR instead
+- Prefer exact values from the spec over "reasonable" guesses
+
+On completion:
+
+- Record deviations under the design/implementation notes **Deviations from Spec** section
+- Link the PR with `{ticket_prefix}-<n>` in the branch name or title (`tasks pr-link` if needed)
+
+## Recording decisions in the source of truth
+
+The document set only works as a source of truth if decisions land in it explicitly. Agents may update project documents, but every decision made during work must be recorded — never applied silently in code alone.
+
+Rules:
+
+- Every content update writes a new revision. Always pass `change_summary` stating what changed and why:
+
+```bash
+noreaster docs update <id> --data '{"content":"...","change_summary":"Recorded decision: switched session storage to Redis (perf, NOR-42)"}'
+```
+
+- Architectural decisions (technology choices, service boundaries, data model direction) go in a new ADR (`doc_type: "adr"`), not buried in an edit. Then update the affected `architecture` / `technical_design` doc to reflect it, with a `change_summary` referencing the ADR.
+- Implementation decisions that deviate from or refine an approved doc: update the governing doc's **Decision Log** / **Deviations from Spec** section with date, decision, rationale, and who decided — plus a `change_summary`.
+- Never rewrite history: use `docs revisions <id>` to inspect prior versions; corrections are new revisions, not silent replacements.
+- Approved docs are gated: content edits to an `approved` doc still record revisions, but status changes go through review (`reviews request` → human approval). If your change invalidates an approval, say so and request re-review rather than working around it.
+
+## Work Discovery
+
+Start here when asked to pick up next work:
+
+```bash
+noreaster my-work
+```
+
+Returns:
+
+- assigned work items for this agent
+- open reviews for the principal owner (or unassigned open reviews)
+- features with open gates (Feature PRD approved awaiting Feature Spec; Feature Spec approved awaiting draft apply)
+- draft runs awaiting apply
+
+## Draft Runs
+
+1. Submit breakdown: `draft-runs submit <featureId> --data '...'`
+2. Humans review in the dashboard
+3. Apply after Feature Spec approval: `draft-runs apply <featureId> <runId> [--data '...']`
+
+Do not invent silent auto-apply behavior.
+
+## NOR Short IDs and PR Linking
+
+- Work items have per-project short IDs rendered as `{ticket_prefix}-<n>` (starting at 1 per project)
+- Branch convention: `{prefix}-<n>-<kebab-title>` (e.g. `aim-12-fix-login`)
+- Put `{ticket_prefix}-<n>` in the branch name or PR title so the webhook can auto-link
+- Manual link: `tasks pr-link <id> --url <github-pr-url>`
+- Unlink: `tasks pr-unlink <id> --url <github-pr-url>`
+- PR merge never silently moves work-item status; humans accept "PR merged — move to done?"
+
+## Work Item Authoring Conventions
+
+When creating or editing work items, prefer:
+
+- **What**: concrete outcome
+- **Why**: user/business reason (include a link back to the source spec)
+- **Acceptance Criteria**: testable checklist of observable outcomes — not implementation details
+
+Breakdown rules (ported from the CTF jira-tickets skill):
+
+- Emit **one work item per affected area** from the project's area registry — never bundle FE and BE into a single item
+- Prefix titles with the area label: `[FE - web] …`, `[BE - api] …` (use `[<area label>]`)
+- Use `tasks list --area <key>` / `my-work` to stay in your lane
+
+Writing for AI tools when authoring specs:
+
+- Prefer exact values ("max file size: 10MB") over vague language
+- Describe UI in words — tools cannot parse Figma links
+- Edge-case table rows become test cases; be exhaustive
+- Include API request/response shapes
+
+Document templates:
+
+```bash
+noreaster docs template design_spec
+noreaster docs template feature_description
+noreaster docs create --data '{"name":"Feature Spec","doc_type":"design_spec","project_id":"<id>","feature_id":"<id>"}'
+```
+
+Empty `content` on create is seeded from the template for that `doc_type`.
+
+## Command Rules
+
+- `--data` must be a JSON object (not an array).
+- Use single quotes around JSON payloads:
+  - `--data '{"title":"Follow up"}'`
+- API failures should be treated as blocking:
+  - non-zero exit code means the command did not complete.
+
+## Auth, Scopes, and Admin Flags
+
+- Operational routes require PAT auth plus route-level scopes (for example `projects.write`, `work_items.write`, `features.write`).
+- Agent scopes come from `ai_agents.metadata.scopes`; `*` grants all scopes.
+- Admin PAT routes depend on feature flags:
+  - `AGENT_ADMIN_PAT_ENABLED=true`
+  - `AGENT_ADMIN_PAT_AGENTS_ENABLED=true`
+  - `AGENT_ADMIN_PAT_TOKENS_ENABLED=true`
+  - `AGENT_ADMIN_PAT_MONITORING_ENABLED=true`
+- If PAT is not supplied on admin routes, fallback auth may use admin session behavior where enabled.
+
+## Core Command Surface
+
+- `my-work`: work discovery inbox
+- `skill install`: copy this skill into local Claude/Cursor skill dirs
+- `tasks`: list/get/create/update/delete + `pr-link` / `pr-unlink`
+- `projects`: list/get/create/update/delete + assignees/calendar color helpers (`github_repos` via update payload)
+- `sprints`: list/get/create/update/delete
+- `customers`: list/get/create/update/delete
+- `prospects`: list/get/create/update/delete + convert
+- `meetings`: list/get/create/update/delete
+- `timeline`: list/get/create/update/delete
+- `docs`: list/get/create/update/transition/revisions/delete
+- `features`: list/get/create/update/transition/delete
+- `reviews`: request/approve/request-changes/check/comment/resolve-comment
+- `draft-runs`: list/get/submit/apply
+- `messages`: list/create
+- `team`: invite/update-role/remove
+- `admin`: agents/tokens/monitoring lifecycle commands
+
+## Standard Workflow
+
+1. Validate environment (`HECHURA_API_BASE_URL`, `HECHURA_AGENT_TOKEN`)
+2. Discover work with `my-work` or targeted list/get
+3. Execute with strict JSON payloads
+4. Verify with get/list
+5. Report concise outcomes and next gates
+
+## Quick Command Examples
+
+```bash
+npm install -g @hechura/noreaster-cli@0.2.2
+noreaster skill install
+noreaster my-work
+noreaster features list --project-id <project-id>
+noreaster draft-runs submit <feature-id> --data '{"document_id":"<design-spec-id>","generated_items":[{"title":"Add login","type":"task","priority":"high"}]}'
+noreaster tasks pr-link <task-id> --url 'https://github.com/owner/repo/pull/12'
+```
+
+## Troubleshooting Playbook
+
+- `Missing token`: set `HECHURA_AGENT_TOKEN` and retry.
+- `Invalid JSON payload`: ensure `--data` is a valid JSON object in single quotes.
+- `401 Unauthorized`: token missing, expired, or revoked.
+- `403 Forbidden`: token scope mismatch or admin PAT route disabled by flags.
+- `409 gate_not_satisfied`: missing lifecycle prerequisite; inspect `gate` and unblock.
+- `429 Too Many Requests`: respect `retry_after_seconds` before retrying.
+- Stale process guidance after a CLI upgrade: run `noreaster skill install` again.
+
+## Known Divergence
+
+- Team admin MCP tools are planned but not primary yet; CLI/API are complete for team operations.
+- Some bulk/reorder/image task workflows still use session routes under `/api/work-items/*` and are not fully mirrored in `/api/agent/tasks/*`.