nubos-pilot 0.1.0

package/templates/AI-SPEC.md

@@ -0,0 +1,90 @@
+---
+phase: {{phase}}
+generated: {{timestamp}}
+generator: np:ai-integration-phase
+---
+
+# Phase {{phase}} — AI Integration Spec
+
+This document is the AI design contract for Phase {{phase}}. It locks the
+framework, implementation patterns, domain rubrics, evaluation strategy,
+guardrails, and production monitoring plan BEFORE the planner creates
+tasks. Re-read this file in full before planning or executing any task
+that produces, consumes, or reasons about model output.
+
+## 1b. Domain Context
+
+Business domain, stakeholders, and expert rubrics. Each rubric ingredient
+(Good / Bad / Stakes) grounds a downstream eval dimension (Section 5).
+
+{{domain_rubric}}
+
+## 2. Framework Selection
+
+Scoring matrix (cost, fit, maturity, ecosystem, lock-in) and final pick.
+Capture the rejected alternative with one-line rationale so downstream
+reviewers can revisit the trade-off.
+
+{{framework_scoring_matrix}}
+
+**Selected:** {{selected_framework}}
+
+**Alternative considered:** {{alternative_framework}}
+
+**Rationale:** {{rationale}}
+
+## 3. Implementation
+
+Canonical entry-point pattern using the selected framework. Copy-paste
+ready; the planner turns this into literal task actions ("wire the client
+exactly as shown below").
+
+```{{language}}
+{{code_patterns}}
+```
+
+Pitfalls and version-specific gotchas called out inline.
+
+## 4b. Pydantic / Typed Models
+
+Structured output contracts (Pydantic, Zod, dataclasses — whatever the
+framework ingests). Use these types everywhere the model returns data;
+free-text parsing is an eval-coverage regression.
+
+```{{language}}
+{{pydantic_models}}
+```
+
+## 5. Eval Dimensions
+
+Named rubric per dimension. Each row states **what is measured**, **how
+it is scored**, and **which Section-1b rubric ingredient it anchors**.
+
+{{eval_dimensions}}
+
+## 6. Guardrails
+
+Hard constraints enforced at runtime — NOT evaluated post-hoc. PII
+redaction, toxicity filters, cost caps, output-format validators, timeout
+bounds. Guardrail violations MUST short-circuit the response.
+
+{{guardrails}}
+
+## 7. Production Monitoring
+
+Tracing, metrics, and alerting contract. Arize Phoenix or detected
+equivalent is the tracing default (OpenTelemetry-compatible). Specify
+dashboard panels + alert thresholds here so they ship in Phase execution,
+not as a retrofit.
+
+{{monitoring_plan}}
+
+## Checklist
+
+- [ ] Framework selected with rationale (Section 2)
+- [ ] Domain rubric ingredients non-empty (Section 1b)
+- [ ] Entry-point code block non-empty (Section 3)
+- [ ] Typed output models present (Section 4b)
+- [ ] At least one eval dimension defined (Section 5)
+- [ ] Guardrails list or explicit N/A rationale (Section 6)
+- [ ] Production-monitoring plan with tracing default (Section 7)

package/templates/CONTEXT.md

@@ -0,0 +1,32 @@
+<!-- Placeholders: canonical_refs_text, code_context_text, created_date, decisions_text, deferred_text, domain_text, phase_name, phase_number, phase_padded, phase_slug, specifics_text -->
+# Phase {{phase_number}}: {{phase_name}} — Context
+
+**Gathered:** {{created_date}}
+
+<domain>
+{{domain_text}}
+</domain>
+
+<decisions>
+{{decisions_text}}
+</decisions>
+
+<canonical_refs>
+{{canonical_refs_text}}
+</canonical_refs>
+
+<code_context>
+{{code_context_text}}
+</code_context>
+
+<specifics>
+{{specifics_text}}
+</specifics>
+
+<deferred>
+{{deferred_text}}
+</deferred>
+
+---
+*Phase: {{phase_padded}}-{{phase_slug}}*
+*Context gathered: {{created_date}}*

package/templates/PLAN.md

@@ -0,0 +1,69 @@
+<!-- Placeholders: autonomous, created_date, depends_on_json, files_modified_yaml, phase, plan, plan_id, requirements_json, wave -->
+---
+phase: "{{phase}}"
+plan: "{{plan}}"
+plan_id: "{{plan_id}}"
+type: execute
+wave: {{wave}}
+depends_on: {{depends_on_json}}
+files_modified:
+{{files_modified_yaml}}
+autonomous: {{autonomous}}
+requirements: {{requirements_json}}
+---
+
+<objective>
+TBD — what does this plan deliver, and why now? One or two sentences.
+
+Purpose: Cover TBD.
+
+Output: TBD (list of artifacts).
+</objective>
+
+<context>
+TBD — @-reference the CONTEXT.md, RESEARCH.md, prior PLAN.md files, and any
+lib modules whose public surface this plan consumes.
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: TBD</name>
+  <files>TBD</files>
+  <read_first>
+    - TBD
+  </read_first>
+  <action>
+TBD — describe the concrete edit or creation. Keep it to a single commit.
+  </action>
+  <verify>
+    <automated>TBD — runnable command that returns exit 0 on success.</automated>
+  </verify>
+  <acceptance_criteria>
+    - TBD
+  </acceptance_criteria>
+  <done>TBD — one-line statement of the task's done state.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-TBD     | TBD      | TBD       | mitigate    | TBD             |
+</threat_model>
+
+<verification>
+- TBD
+</verification>
+
+<success_criteria>
+- TBD
+</success_criteria>
+
+<output>
+After completion, create `.nubos-pilot/phases/{{phase}}-<slug>/{{plan_id}}-SUMMARY.md` covering: TBD.
+</output>
+
+---
+*Plan drafted: {{created_date}}*

package/templates/PROJECT.md

@@ -0,0 +1,60 @@
+<!-- Placeholders: core_value, created_date, first_milestone_name, first_phase_name, primary_constraints, project_name -->
+# {{project_name}}
+
+## Project
+
+{{project_name}} — {{core_value}}
+
+## What This Is
+
+{{project_name}} is an early-stage project. Update this section after the first
+phase ships with a concrete 2-3 sentence description of what the product does
+and who it serves. Use the user's language and framing.
+
+## Core Value
+
+{{core_value}}
+
+If everything else fails, this one sentence must remain true. It drives
+prioritization when tradeoffs arise.
+
+## Constraints
+
+{{primary_constraints}}
+
+## Current Focus
+
+Milestone: **{{first_milestone_name}}**
+First phase: **{{first_phase_name}}**
+
+This section is updated by `np:next` and milestone transitions. It reflects
+what is actively being worked on right now, not the full roadmap (see
+`ROADMAP.md`).
+
+## Key Decisions
+
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Initial scaffold via np:new-project | Greenfield project bootstrap (D-28) | — Pending |
+
+## Evolution
+
+PROJECT.md evolves throughout the project lifecycle.
+
+**After each phase transition:**
+1. Requirements invalidated? → Move to Out of Scope in REQUIREMENTS.md with reason
+2. Requirements validated? → Move to Validated in REQUIREMENTS.md with phase reference
+3. New requirements emerged? → Add to REQUIREMENTS.md Active list
+4. Decisions to log? → Add to Key Decisions above
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone:**
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Update Current Focus with next milestone/phase
+
+---
+*Created: {{created_date}}*
+*Last updated: {{created_date}} after np:new-project*

package/templates/REQUIREMENTS.md

@@ -0,0 +1,38 @@
+<!-- Placeholders: core_value, created_date, first_milestone_name, project_name -->
+# Requirements: {{project_name}}
+
+**Defined:** {{created_date}}
+**Core Value:** {{core_value}}
+
+## {{first_milestone_name}} Requirements
+
+Requirements for the first milestone. Each should map to one or more roadmap
+phases. Edit these and add more after `np:new-project` completes.
+
+<!-- TBD: first requirement -->
+- [ ] **REQ-01**: TBD — edit this line with a checkable requirement
+
+<!-- TBD: add more requirements here as they emerge -->
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+<!-- TBD: add exclusions as boundaries become clear -->
+
+| Feature | Reason |
+|---------|--------|
+| *(none yet)* | — |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap evolution.
+
+<!-- Filled by /np:plan-phase -->
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| REQ-01      | TBD   | Pending |
+
+---
+*Requirements defined: {{created_date}}*

package/templates/SECURITY.md

@@ -0,0 +1,61 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+threats_open: 0
+asvs_level: 1
+created: {date}
+---
+
+# Phase {N} — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| {boundary} | {description} | {data type / sensitivity} |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-{N}-01 | {STRIDE category} | {component} | {mitigate / accept / transfer} | {control or reference} | open |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+
+*Accepted risks do not resurface in future audit runs.*
+
+*If none: "No accepted risks."*
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| {YYYY-MM-DD} | {N} | {N} | {N} | {name / agent} |
+
+---
+
+## Sign-Off
+
+- [ ] All threats have a disposition (mitigate / accept / transfer)
+- [ ] Accepted risks documented in Accepted Risks Log
+- [ ] `threats_open: 0` confirmed
+- [ ] `status: verified` set in frontmatter
+
+**Approval:** {pending / verified YYYY-MM-DD}

package/templates/UI-SPEC.md

@@ -0,0 +1,64 @@
+---
+phase: {{phase}}
+generated: {{timestamp}}
+generator: np:ui-phase
+---
+
+# Phase {{phase}} — UI Spec
+
+This document is the UI design contract for Phase {{phase}}. It locks the
+six visual pillars BEFORE the planner creates tasks so execution stays
+consistent with brand and system. Re-read this file in full before any
+task that modifies user-facing surface.
+
+## 1. Spacing
+
+Spacing scale, layout grid, vertical rhythm, and breakpoint math.
+
+{{spacing_rules}}
+
+## 2. Typography
+
+Type scale, font stacks, weights, line-heights, and letter-spacing.
+Include usage rules (headings vs body, emphasis, numeric alignment).
+
+{{typography_scale}}
+
+## 3. Color
+
+Palette with token names, contrast contracts (WCAG AA/AAA evidence), and
+semantic intent (danger, warning, info, success, neutral). Include
+dark/light variants if applicable.
+
+{{color_palette}}
+
+## 4. Copywriting
+
+Voice, tone, persona. Reusable microcopy patterns (CTAs, empty states,
+errors, confirmations). Include profanity / tone guardrails.
+
+{{voice_and_tone}}
+
+## 5. Design System
+
+Component inventory from the chosen design system (shadcn/ui, Radix,
+Material, bespoke). Which components are already-wired vs TODO. Which
+design-tokens map to which Tailwind/CSS-variable name.
+
+{{design_system_components}}
+
+## 6. Components
+
+Phase-specific component contracts: prop signature, accessibility
+contract (ARIA roles/labels, keyboard nav), state machine, edge cases.
+
+{{component_inventory}}
+
+## Checklist
+
+- [ ] Spacing scale defined with evidence (Section 1)
+- [ ] Typography scale + font-stack pinned (Section 2)
+- [ ] Color palette with contrast contract (Section 3)
+- [ ] Voice and microcopy patterns captured (Section 4)
+- [ ] Design-system inventory with token map (Section 5)
+- [ ] Component contracts per phase (Section 6)

package/templates/VALIDATION.md

@@ -0,0 +1,76 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: {date}
+---
+
+# Phase {N} — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | {pytest 7.x / jest 29.x / vitest / go test / other} |
+| **Config file** | {path or "none — Wave 0 installs"} |
+| **Quick run command** | `{quick command}` |
+| **Full suite command** | `{full command}` |
+| **Estimated runtime** | ~{N} seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `{quick run command}`
+- **After every plan wave:** Run `{full suite command}`
+- **Before `/np:verify-work`:** Full suite must be green
+- **Max feedback latency:** {N} seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| {N}-01-01 | 01 | 1 | REQ-{XX} | T-{N}-01 / — | {expected secure behavior or "N/A"} | unit | `{command}` | ✅ / ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `{tests/test_file.py}` — stubs for REQ-{XX}
+- [ ] `{tests/conftest.py}` — shared fixtures
+- [ ] `{framework install}` — if no framework detected
+
+*If none: "Existing infrastructure covers all phase requirements."*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| {behavior} | REQ-{XX} | {reason} | {steps} |
+
+*If none: "All phase behaviors have automated verification."*
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < {N}s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** {pending / approved YYYY-MM-DD}

package/templates/claude/payload/README.md

@@ -0,0 +1,11 @@
+# nubos-pilot Source Payload
+
+This directory is the SOURCE TREE for the installer. Content ships here and is COPIED by `bin/install.js` into `.claude/nubos-pilot/` at install time.
+
+Subdirectories (populated in Phase 8 and onwards):
+- `workflows/` — `.md` commands copied into `.claude/nubos-pilot/workflows/`
+- `agents/` — agent `.md` files
+- `hooks/` — hook scripts
+- `templates/` — scaffolding templates
+
+See `.planning/phases/07-install-npx-flow/07-RESEARCH.md` §Recommended Project Structure for the full layout.

package/templates/opencode/opencode.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "paths": [".claude/agents/"]
+  }
+}

package/templates/opencode/payload/AGENTS.md

@@ -0,0 +1,9 @@
+# AGENTS.md (OpenCode)
+
+> This file is regenerated by nubos-pilot on install. User edits will be preserved
+> only outside the managed block.
+
+<!-- nubos-pilot:begin v1 -->
+<!-- do not edit manually — managed by npx nubos-pilot -->
+(Managed content rewritten by installer.)
+<!-- nubos-pilot:end -->