@hechura/noreaster-cli 0.2.1 → 0.2.2

package/dist/document-templates.js

@@ -12,6 +12,10 @@ exports.TEMPLATE_DOC_TYPES = [
     "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").
@@ -299,6 +303,139 @@ ${AI_WRITING_HINT}
 
 ## 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 = {
@@ -309,6 +446,10 @@ const TEMPLATES = {
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hechura/noreaster-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI for Hechura Noreaster agent API access",
   "repository": {
     "type": "git",

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

@@ -10,7 +10,7 @@ Use this skill for operational work in Noreaster through the official agent CLI
 ## Execution Defaults
 
 1. Prefer the published CLI:
-   - `npx @hechura/noreaster-cli@0.2.1 <command>` or `noreaster <command>` after global install (`npm install -g @hechura/noreaster-cli@0.2.1`)
+   - `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`
@@ -30,17 +30,22 @@ PRD → Feature → Feature PRD (feature_description) → Feature Spec (design_s
 → Work Items → Implementation Plan docs → GitHub PRs
 ```
 
-### Doc types vs labels
+### The source-of-truth document set
 
-UI labels are for humans; CLI/API payloads use `doc_type` values:
+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` |
-| --- | --- |
-| Feature PRD | `feature_description` |
-| Feature Spec | `design_spec` |
-| Technical Architecture | `architecture` |
-| Design System | `design_system` |
-| PRD | `prd` |
+| 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>`.
 
@@ -50,7 +55,7 @@ Ownership defaults:
 - 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 `NOR-<n>`
+- PRs: linked manually or via inbound webhook matching `{ticket_prefix}-<n>` (e.g. `AIM-12`)
 
 ## Lifecycle Gates
 
@@ -74,6 +79,8 @@ Before implementing a work item, load the governing docs — do not invent contr
 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:
@@ -87,7 +94,24 @@ Compliance rules while coding:
 On completion:
 
 - Record deviations under the design/implementation notes **Deviations from Spec** section
-- Link the PR with `NOR-<n>` in the branch name or title (`tasks pr-link` if needed)
+- 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
 
@@ -114,9 +138,9 @@ Do not invent silent auto-apply behavior.
 
 ## NOR Short IDs and PR Linking
 
-- Work items have global short IDs rendered as `NOR-<n>`
-- Branch convention: `nor-<n>-<kebab-title>`
-- Put `NOR-<n>` in the branch name or PR title so the webhook can auto-link
+- 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?"
@@ -201,7 +225,7 @@ Empty `content` on create is seeded from the template for that `doc_type`.
 ## Quick Command Examples
 
 ```bash
-npm install -g @hechura/noreaster-cli@0.2.1
+npm install -g @hechura/noreaster-cli@0.2.2
 noreaster skill install
 noreaster my-work
 noreaster features list --project-id <project-id>