@jhizzard/termdeck 0.8.0 → 0.9.0

package/packages/cli/src/templates.js

@@ -0,0 +1,84 @@
+'use strict';
+
+// Sprint 37 T2 — Shared template loader.
+//
+// `init-project.js` (T2) and the dashboard orchestration-preview endpoint (T3)
+// both render the same set of project-scaffolding templates. This module is
+// the single source of truth for where they live, what they're named, what
+// dest path they map to inside a generated project tree, and how
+// `{{placeholder}}` substitution works.
+//
+// Naming convention for templates in packages/cli/templates/:
+//   - Files are flat in this dir (no subdirs).
+//   - Subdirectory placement in the GENERATED project tree is encoded by a
+//     hyphenated prefix (e.g. `docs-orchestration-README.md.tmpl` lands at
+//     `docs/orchestration/README.md`). The MANIFEST below is the only
+//     authoritative source for those mappings — the `name` field is the
+//     human-readable identifier used in tests and UI, the `file` field is
+//     the on-disk template filename, and `targetPath` is the dest path
+//     RELATIVE to the project root.
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+// The 8 templates that compose the project-scaffolding tree. Order is the
+// order the init-project generator writes them and the order the dashboard
+// preview surfaces them. T3 — iterate this directly via listTemplates().
+const MANIFEST = [
+  { name: 'CLAUDE.md',                     file: 'CLAUDE.md.tmpl',                     targetPath: 'CLAUDE.md' },
+  { name: 'CONTRADICTIONS.md',             file: 'CONTRADICTIONS.md.tmpl',             targetPath: 'CONTRADICTIONS.md' },
+  { name: 'project_facts.md',              file: 'project_facts.md.tmpl',              targetPath: 'project_facts.md' },
+  { name: 'README.md',                     file: 'README.md.tmpl',                     targetPath: 'README.md' },
+  { name: 'docs/orchestration/README.md',  file: 'docs-orchestration-README.md.tmpl',  targetPath: path.join('docs', 'orchestration', 'README.md') },
+  { name: 'docs/orchestration/RESTART-PROMPT.md.tmpl', file: 'RESTART-PROMPT.md.tmpl', targetPath: path.join('docs', 'orchestration', 'RESTART-PROMPT.md.tmpl') },
+  { name: '.claude/settings.json',         file: '.claude-settings.json.tmpl',         targetPath: path.join('.claude', 'settings.json') },
+  { name: '.gitignore',                    file: '.gitignore.tmpl',                    targetPath: '.gitignore' },
+];
+
+// name → manifest entry, for callers that want lookup by name (T3's preview UI).
+const BY_NAME = Object.fromEntries(MANIFEST.map((e) => [e.name, e]));
+
+// Replace {{key}} occurrences with vars[key]. Unknown keys are left untouched
+// so a typo is visible in the output rather than silently rendering empty.
+function renderString(source, vars) {
+  return source.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    if (Object.prototype.hasOwnProperty.call(vars, key)) return String(vars[key]);
+    return match;
+  });
+}
+
+// Resolve a caller-supplied identifier to a manifest entry. Accepts the
+// human-readable `name` ('CLAUDE.md') OR the on-disk template filename
+// ('CLAUDE.md.tmpl') so both conventions work from caller code.
+function resolveEntry(identifier) {
+  const direct = BY_NAME[identifier];
+  if (direct) return direct;
+  const byFile = MANIFEST.find((e) => e.file === identifier);
+  if (byFile) return byFile;
+  throw new Error(`Unknown template: ${identifier}`);
+}
+
+function readTemplate(identifier) {
+  const entry = resolveEntry(identifier);
+  return fs.readFileSync(path.join(TEMPLATES_DIR, entry.file), 'utf8');
+}
+
+function renderTemplate(identifier, vars) {
+  return renderString(readTemplate(identifier), vars || {});
+}
+
+// Returns the manifest entries (cloned so callers can't mutate state).
+function listTemplates() {
+  return MANIFEST.map((e) => ({ ...e }));
+}
+
+module.exports = {
+  TEMPLATES_DIR,
+  MANIFEST,
+  readTemplate,
+  renderTemplate,
+  listTemplates,
+  _renderString: renderString,
+};

package/packages/cli/templates/.claude-settings.json.tmpl

@@ -0,0 +1,32 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(pwd)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(grep:*)",
+      "Bash(rg:*)",
+      "Bash(find:*)",
+      "Bash(wc:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(node --version)",
+      "Bash(npm --version)",
+      "Bash(npm view:*)",
+      "Bash(npm test:*)",
+      "Bash(npm run:*)",
+      "Bash(npm ls:*)",
+      "Read(//{{project_path}}/**)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(npm publish:*)"
+    ]
+  }
+}

package/packages/cli/templates/.gitignore.tmpl

@@ -0,0 +1,28 @@
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# TermDeck local state (per-session logs, sqlite)
+.termdeck/
+
+# Build / dist
+dist/
+build/
+.next/
+.turbo/
+coverage/

package/packages/cli/templates/CLAUDE.md.tmpl

@@ -0,0 +1,35 @@
+# {{project_name}} — agent read-order
+
+This is the project router for AI coding agents (Claude Code, Codex, etc.) working in `{{project_name}}`. It points at the rest of the docs in the order an agent should read them.
+
+## Before any task — read order
+
+1. **`memory_recall(project="{{project_name}}", query="<task topic>")`** — always first if a memory MCP is wired up.
+2. **`~/.claude/CLAUDE.md`** — your global rules (memory-first, time check, session-end rituals, message-inject mandates).
+3. **This file** — you already are.
+4. **`project_facts.md`** — stable facts about this project: paths, conventions, dependencies, deployment target.
+5. **`CONTRADICTIONS.md`** — audit trail of facts/decisions that have changed over time. If something here contradicts `project_facts.md`, the entry here is more recent.
+6. **`docs/orchestration/README.md`** — index of orchestration docs (4+1 sprint plans, restart prompts, etc.) if you're running multi-agent work.
+7. **The ONE task-doc that applies:**
+
+| If you're going to... | Read |
+|---|---|
+| Add a feature, fix a bug, refactor | (project's own architecture doc, e.g. `docs/ARCHITECTURE.md` once you create it) |
+| Ship a release | (project's own release doc, e.g. `docs/RELEASE.md` once you create it) |
+| Run or coordinate a 4+1 sprint | `docs/orchestration/README.md` + active `docs/sprint-N-<name>/PLANNING.md` |
+
+8. **Then begin.**
+
+## Hard rules
+
+- **Never publish or push to a shared branch without reading the project's release doc first** (if one exists). Publish-order, auth-method, and any audit-trail bumps are easy to get wrong from memory.
+- **Inside a 4+1 sprint lane: no version bumps, no CHANGELOG edits, no commits.** The orchestrator handles those at sprint close.
+- Add project-specific hard rules (language choices, build-step decisions, off-limits files) below this line as the project takes shape.
+
+## Current state pointer
+
+For the live state of this project (versions, branches, deploy URLs), prefer `git log -1`, `npm view`, or whatever ground-truth source applies — over anything written here. This file is intentionally a pointer, not a source of truth.
+
+---
+
+_Generated by `termdeck init --project` on {{generated_at}} (TermDeck v{{termdeck_version}})._

package/packages/cli/templates/CONTRADICTIONS.md.tmpl

@@ -0,0 +1,30 @@
+# {{project_name}} — Contradictions ledger
+
+Append-only record of facts and decisions in this project that have **changed** over time. The most recent entry on a topic is the current truth. Older entries are kept for the trail, not for reference.
+
+## Why this file exists
+
+Memory systems (and humans) accumulate stale beliefs. When an agent reads `project_facts.md` and acts on something that's no longer true, the failure mode is silent — the wrong code ships, the wrong link gets sent, the wrong assumption hardens. This ledger is the place to record the *correction* the moment a fact flips, so the next session can compare.
+
+## How to use this file
+
+When you discover that a previously-recorded fact is wrong (in `project_facts.md`, in a memory store, in your own assumptions), append an entry below. Keep the old fact visible — don't rewrite history.
+
+## Entry format
+
+```
+## YYYY-MM-DD — <one-line topic>
+
+**Old:** <what we used to believe>
+**New:** <what's true now>
+**Why it changed:** <discovery, decision, external change>
+**Where the old belief lives:** <file/path/memory-id, so future sessions know what to also update>
+```
+
+---
+
+_(no entries yet — append above this line as contradictions surface)_
+
+---
+
+_Generated by `termdeck init --project` on {{generated_at}} (TermDeck v{{termdeck_version}})._

package/packages/cli/templates/README.md.tmpl

@@ -0,0 +1,15 @@
+# {{project_name}}
+
+_(One-line description of this project goes here.)_
+
+## For humans
+
+_(Quickstart, install, usage. Edit this section as the project takes shape.)_
+
+## For AI agents
+
+Read **`CLAUDE.md`** first. It's the agent read-order: which docs to read in which order before doing any work in this repo.
+
+---
+
+_Scaffolded with TermDeck v{{termdeck_version}} on {{generated_at}}._

package/packages/cli/templates/RESTART-PROMPT.md.tmpl

@@ -0,0 +1,38 @@
+# {{project_name}} — Restart prompt template
+
+Copy this file to `RESTART-PROMPT-YYYY-MM-DD.md` at the end of a session, fill in the blanks, and the next agent will be able to resume cleanly by reading just this one document.
+
+---
+
+You are picking up work on **{{project_name}}** at `{{project_path}}`.
+
+## Boot sequence
+
+1. `memory_recall(project="{{project_name}}", query="<topic the user signaled at session start>")` — if a memory MCP is wired up.
+2. `memory_recall(query="recent decisions and bugs")` — broader context across all projects.
+3. Read `~/.claude/CLAUDE.md` (global rules).
+4. Read `{{project_path}}/CLAUDE.md` (this project's read-order).
+5. Read `{{project_path}}/project_facts.md` and `{{project_path}}/CONTRADICTIONS.md`.
+6. Read this file in full (the rest of the sections below).
+7. Then begin.
+
+## What was done in the last session
+
+_(Bullet list. Concrete items: files changed, decisions locked, versions shipped, bugs fixed. No fluff.)_
+
+## What is queued next
+
+_(What the next session should pick up. The smaller and more concrete, the better.)_
+
+## Open follow-ups / known issues
+
+_(Things deliberately deferred, things flagged as broken, anything the next session should be aware of before touching related code.)_
+
+## Where to find more context
+
+- `{{project_path}}/docs/orchestration/` — sprint plans, restart prompts.
+- _(Add: links to relevant tickets, dashboards, deploy URLs.)_
+
+---
+
+_Template generated by `termdeck init --project` on {{generated_at}} (TermDeck v{{termdeck_version}})._

package/packages/cli/templates/docs-orchestration-README.md.tmpl

@@ -0,0 +1,29 @@
+# {{project_name}} — Orchestration docs
+
+This directory holds the artifacts of multi-agent orchestration work in `{{project_name}}` — primarily 4+1 sprint plans and restart prompts.
+
+## What lives here
+
+- **`RESTART-PROMPT.md.tmpl`** — template for per-session restart prompts. Copy to `RESTART-PROMPT-YYYY-MM-DD.md` at the end of a session; the next agent reads the latest dated restart prompt to pick up where you left off.
+- **`sprint-N-<name>/PLANNING.md`** _(when sprints exist)_ — the single source of truth for what a sprint is doing, divided into T1–T4 lane briefings.
+- **`sprint-N-<name>/STATUS.md`** _(when sprints exist)_ — append-only status log. Each lane posts FINDING / FIX-PROPOSED / DONE entries.
+- **`sprint-N-<name>/T<n>-<lane>.md`** _(when sprints exist)_ — full briefing for one lane.
+
+## The 4+1 sprint pattern (short version)
+
+Four parallel agent panels (T1–T4) each work in a single lane (a tightly scoped set of files). A fifth orchestrator panel coordinates: spawns the four, monitors STATUS.md, handles version bumps + CHANGELOG + commits at sprint close.
+
+Lane discipline matters:
+- T1–T4 stay in their lane. No version bumps, no CHANGELOG edits, no commits inside a lane.
+- All cross-lane communication happens through `STATUS.md` (append-only).
+- The orchestrator is the only panel that ships.
+
+If you're running TermDeck, the orchestrator can spawn and inject the four panels through the dashboard sprint runner. If you're not, the orchestrator manually opens four terminals and pastes (or scripts) the boot prompts.
+
+## Restart prompts
+
+At the end of every working session, write a `RESTART-PROMPT-YYYY-MM-DD.md` containing exactly what the next session needs to read (in order) to resume cleanly. The template here is a starting point — adapt as the project gets specific.
+
+---
+
+_Generated by `termdeck init --project` on {{generated_at}} (TermDeck v{{termdeck_version}})._

package/packages/cli/templates/project_facts.md.tmpl

@@ -0,0 +1,39 @@
+# {{project_name}} — Project facts
+
+Stable, slow-changing facts about this project. The kind of thing an agent needs to know up front to avoid asking obvious questions or making bad assumptions.
+
+If a fact here goes stale, do **not** silently rewrite it. Append to `CONTRADICTIONS.md` first (so the change is recorded), then update this file.
+
+## Identity
+
+- **Name:** {{project_name}}
+- **Path:** `{{project_path}}`
+- **Created:** {{generated_at}}
+- **Scaffolded with:** TermDeck v{{termdeck_version}}
+
+## Stack
+
+- **Language / runtime:** _(fill in once chosen)_
+- **Package manager:** _(npm, pnpm, uv, cargo, etc.)_
+- **Test runner:** _(node:test, vitest, pytest, etc.)_
+- **Linter / formatter:** _(eslint, ruff, etc.)_
+
+## Deployment
+
+- **Target:** _(npm, Vercel, Supabase Edge, self-hosted, internal-only, etc.)_
+- **Current live version:** _(see `git log` / `npm view` / deploy dashboard for ground truth)_
+
+## Conventions
+
+- **Branching:** _(trunk-based, feature branches, etc.)_
+- **Commit style:** _(conventional commits, free-form, etc.)_
+- **Sprint pattern:** _(if running 4+1 sprints, point at `docs/orchestration/`)_
+- **Release process:** _(point at `docs/RELEASE.md` if/when one exists)_
+
+## Off-limits / be-careful zones
+
+- _(list any files, branches, or systems that need extra caution — e.g. "production database is shared with X")_
+
+---
+
+_Generated by `termdeck init --project` on {{generated_at}} (TermDeck v{{termdeck_version}})._