@chinhae/atw-cli 0.1.0

package/dist/templates/common/commands/start.md

@@ -0,0 +1,68 @@
+# Start Session
+
+Initialize an ATW-managed development session. This platform has no session-start hook, so manually load the equivalent compact context by following these steps.
+
+---
+
+## Step 1: Current state
+Identity, git status, current task, active tasks, journal location.
+
+```bash
+{{PYTHON_CMD}} ./.atw/scripts/get_context.py
+```
+
+If this output includes a line beginning `ATW update available:`, copy the full line verbatim when summarizing session context. Do not shorten operational command hints.
+
+## Step 2: Workflow overview
+Compact Phase Index, request triage rules, planning artifact contract, and the step-detail command.
+
+```bash
+{{PYTHON_CMD}} ./.atw/scripts/get_context.py --mode phase
+```
+
+Full guide in `.atw/workflow.md` (read on demand).
+
+## Step 3: Guideline indexes
+Discover packages + spec layers, then read each relevant index file.
+
+```bash
+{{PYTHON_CMD}} ./.atw/scripts/get_context.py --mode packages
+cat .atw/spec/guides/index.md
+cat .atw/spec/<package>/<layer>/index.md   # for each relevant layer
+```
+
+Index files list the specific guideline docs to read when you actually start coding.
+
+## Step 4: Decide next action
+Step 1 gave you the active task's `status`. The stage *is* the route — each of the six stages maps to one step in the Phase Index you loaded in Step 2:
+
+- `status=discover` → **1.1**
+- `status=specify` → **1.2**, then **1.3** on sub-agent-dispatch platforms
+- `status=slice` → **1.4**
+- `status=implement` → **2.1**
+- `status=accept` → **3.1**
+- `status=completed` on a task still under `.atw/tasks/` → **3.2**. The archive was interrupted partway; re-run `task.py archive <task>` to finish it.
+
+Load the step detail before acting on it:
+
+```bash
+{{PYTHON_CMD}} ./.atw/scripts/get_context.py --mode phase --step <X.X> --platform {{CLI_FLAG}}
+```
+
+`{{CMD_REF:continue}}` carries the same six stages with their artifact checks and stop points — use it when you need more than the step number.
+
+**No active task** → classify first. For simple conversation / small task, ask only whether this turn should create an ATW task. For complex work, ask whether you may create an ATW task and enter `discover` — that ask is **stop ①**, and task creation is step **1.0**. If the user says no, skip ATW for this session.
+
+---
+
+## Skill routing (quick reference)
+
+| User intent | Skill |
+|---|---|
+| New feature / unclear requirements | `atw-askme` |
+| About to write code | `atw-before-dev` |
+| Done coding / quality check | `atw-code-review` |
+| Stuck / fixed same bug multiple times | `atw-diagnosing-bugs` |
+| Learned something worth capturing | `atw-update-spec` |
+
+Full rules + anti-rationalization table in `.atw/workflow.md`.

package/dist/templates/common/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Common templates — single source of truth for all platforms.
+ *
+ * These templates contain {{placeholders}} that are resolved per-platform
+ * by resolvePlaceholders() in configurators/shared.ts.
+ *
+ * Directory structure:
+ *   common/
+ *   ├── commands/        # Templates that stay as slash commands
+ *   ├── skills/          # Single-file templates that become auto-triggered skills
+ *   └── bundled-skills/  # Multi-file built-in skills with references/assets
+ */
+export interface CommonTemplate {
+    /** Template name without extension (e.g., "start", "before-dev") */
+    name: string;
+    /** Raw content with {{placeholders}} — must be resolved before writing */
+    content: string;
+}
+export interface CommonBundledSkillFile {
+    /** POSIX path relative to the skill directory, e.g. "references/core.md" */
+    relativePath: string;
+    /** Raw content with {{placeholders}} — must be resolved before writing */
+    content: string;
+}
+export interface CommonBundledSkill {
+    /** Skill directory name, e.g. "atw-meta" */
+    name: string;
+    /** Files that must be written under the skill directory */
+    files: CommonBundledSkillFile[];
+}
+/**
+ * Get all command templates (stay as slash commands on all platforms).
+ * Results are cached after first call.
+ */
+export declare function getCommandTemplates(): CommonTemplate[];
+/**
+ * Get all skill templates (become auto-triggered skills on supporting platforms).
+ * Results are cached after first call.
+ */
+export declare function getSkillTemplates(): CommonTemplate[];
+/**
+ * Get all multi-file built-in skills.
+ *
+ * These are copied as complete skill directories so references and assets stay
+ * lazy-loadable instead of being flattened into one oversized SKILL.md.
+ */
+export declare function getBundledSkillTemplates(): CommonBundledSkill[];
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD;AAuCD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAM/D"}

package/dist/templates/common/index.js

@@ -0,0 +1,104 @@
+/**
+ * Common templates — single source of truth for all platforms.
+ *
+ * These templates contain {{placeholders}} that are resolved per-platform
+ * by resolvePlaceholders() in configurators/shared.ts.
+ *
+ * Directory structure:
+ *   common/
+ *   ├── commands/        # Templates that stay as slash commands
+ *   ├── skills/          # Single-file templates that become auto-triggered skills
+ *   └── bundled-skills/  # Multi-file built-in skills with references/assets
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function readTemplate(relativePath) {
+    return readFileSync(join(__dirname, relativePath), "utf-8");
+}
+function listMarkdownFiles(dir) {
+    try {
+        return readdirSync(join(__dirname, dir))
+            .filter((f) => f.endsWith(".md"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// Cached results — files don't change during a CLI run
+let cachedCommands;
+let cachedSkills;
+let cachedBundledSkills;
+/**
+ * Get all command templates (stay as slash commands on all platforms).
+ * Results are cached after first call.
+ */
+export function getCommandTemplates() {
+    cachedCommands ??= listMarkdownFiles("commands").map((file) => ({
+        name: file.replace(/\.md$/, ""),
+        content: readTemplate(`commands/${file}`),
+    }));
+    return cachedCommands;
+}
+/**
+ * Get all skill templates (become auto-triggered skills on supporting platforms).
+ * Results are cached after first call.
+ */
+export function getSkillTemplates() {
+    cachedSkills ??= listMarkdownFiles("skills").map((file) => ({
+        name: file.replace(/\.md$/, ""),
+        content: readTemplate(`skills/${file}`),
+    }));
+    return cachedSkills;
+}
+function listDirectories(dir) {
+    try {
+        return readdirSync(join(__dirname, dir))
+            .filter((entry) => statSync(join(__dirname, dir, entry)).isDirectory())
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function toPosixRelativePath(root, filePath) {
+    return relative(root, filePath).split(sep).join("/");
+}
+function listBundledSkillFiles(skillDir) {
+    const root = join(__dirname, "bundled-skills", skillDir);
+    const files = [];
+    function walk(dir) {
+        for (const entry of readdirSync(dir)) {
+            const fullPath = join(dir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            }
+            else {
+                files.push({
+                    relativePath: toPosixRelativePath(root, fullPath),
+                    content: readFileSync(fullPath, "utf-8"),
+                });
+            }
+        }
+    }
+    walk(root);
+    return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+/**
+ * Get all multi-file built-in skills.
+ *
+ * These are copied as complete skill directories so references and assets stay
+ * lazy-loadable instead of being flattened into one oversized SKILL.md.
+ */
+export function getBundledSkillTemplates() {
+    cachedBundledSkills ??= listDirectories("bundled-skills").map((name) => ({
+        name,
+        files: listBundledSkillFiles(name),
+    }));
+    return cachedBundledSkills;
+}
+//# sourceMappingURL=index.js.map

package/dist/templates/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/common/skills/before-dev.md

@@ -0,0 +1,44 @@
+Read the relevant development guidelines before starting your task.
+
+Execute these steps:
+
+1. **Read current task artifacts**:
+   - `prd.md` for requirements and acceptance criteria
+      
+2. **Discover packages and their spec layers**:
+   ```bash
+   python3 ./.atw/scripts/get_context.py --mode packages
+   ```
+
+3. **Identify which specs apply** to your task based on:
+   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
+   - What type of work (backend, frontend, unit-test, docs, etc.)
+   - Any spec/research paths referenced by the task artifacts
+
+4. **Read the spec index** for each relevant module:
+   ```bash
+   cat .atw/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Pre-Development Checklist"** section in the index.
+
+5. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+6. **Always read shared guides**:
+   ```bash
+   cat .atw/spec/guides/index.md
+   ```
+
+7. **For a non-trivial task, state the change boundary before writing code.** Non-trivial means it touches more than one file, crosses a layer, changes a public interface, or edits code you did not just write. Write down:
+   - the smallest behavior gap between what happens now and what should happen
+   - where that behavior actually lives (not where it is easiest to intercept)
+   - which files you expect to change, and why each one is necessary
+   - what you are explicitly not doing in this task
+   - if a local refactor is needed, how you will show it did not change behavior
+
+   A small, well-scoped change does not need this — do it directly.
+
+   If the real scope turns out to be clearly larger than this, say so and why before continuing. Do not widen the change on your own.
+
+8. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+
+This step is **mandatory** before writing any code.

package/dist/templates/common/skills/brainstorm.md

@@ -0,0 +1,194 @@
+# ATW Brainstorm
+
+## Non-Negotiable Planning Contract
+
+A request to build, implement, fix, refactor, or "go ahead" is not approval to leave planning. Task-creation consent is also not implementation approval.
+
+For every non-trivial task, the user must respond at least once after the initial request before implementation begins. If no clarification is needed, that response must approve the final planning summary described below.
+
+While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, end the turn with exactly one highest-value question. Do not edit product code, dispatch implementation, or run `task.py start`.
+
+## Non-Negotiable Evidence Rule
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+This is mandatory. Before asking the user a question, first check whether the answer is already available in code, tests, configs, docs, existing specs, or task history.
+
+Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, acceptance behavior, or decisions that remain ambiguous after inspection.
+
+Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
+
+---
+
+Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
+
+## Preconditions
+
+Use this skill only after task-creation consent has been given and the user is ready to enter ATW's `discover` stage.
+
+If no task exists yet, create one:
+
+```bash
+TASK_DIR=$({{PYTHON_CMD}} ./.atw/scripts/task.py create "<short task title>" --description "<one-line summary>" --slug <slug>)
+```
+
+Use a concise title from the user's request. Both the title and `--description` must be non-empty — `create` rejects blanks, and a record with either one empty is refused at archive. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
+
+`task.py create` creates the default `prd.md`. Update that file with the current understanding before asking follow-up questions.
+
+## Planning Flow
+
+1. Capture the user's request and initial known facts in `prd.md`.
+2. Inspect available evidence before asking questions:
+   - code, tests, fixtures, and configs
+   - README files, docs, existing specs, and domain notes
+   - related ATW tasks, research files, and session history when present
+3. Separate what you found into:
+   - confirmed facts
+   - product intent still needed from the user
+   - scope or risk decisions still needed from the user
+   - likely out-of-scope items
+4. If a user-owned decision remains, ask the single highest-value question, include your recommendation and trade-off, then stop. Do not perform implementation work in the same turn.
+5. After each user answer, update `prd.md`, recompute the decision inventory, and repeat from step 2.
+6. When no user-owned decision remains, fold the technical design into `prd.md`; execution order for complex tasks comes from slicing into tickets, not from a planning doc.
+7. Run the requirement convergence gate, then the PRD convergence pass.
+8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
+9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If the artifacts change materially after approval, repeat the final review.
+
+Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
+
+## Question Rules
+
+Ask only one question per message.
+
+Each question must include:
+
+- the decision needed
+- why the answer matters
+- your recommended answer
+- the trade-off if the user chooses differently
+
+Do not ask process questions such as whether to search, inspect files, or continue brainstorming. Do the evidence work directly. Ask the user only when the remaining issue is a product decision, preference, scope boundary, or risk tolerance choice.
+
+Recommendations are not default selections. Never choose a recommended product decision on the user's behalf merely because the user asked for implementation.
+
+Do not manufacture clarification questions when the request and repository evidence already resolve every decision. In that case, proceed directly to the final planning summary, which still requires a subsequent explicit approval.
+
+The final review is a required phase-transition gate, not a prohibited process question. Task-creation consent, the initial implementation request, and approval given before the latest final summary do not satisfy this gate.
+
+## Thinking Framework: First Principles Analysis
+
+When requirements are vague, solutions feel over-engineered, or you're about to add complexity "because everyone does" — decompose to fundamental truths before reasoning upward.
+
+### Step 1: Restate the Problem
+
+Strip away implementation details to one sentence.
+
+> Bad: "We need to add Redis caching to the user profile endpoint"
+> Good: "User profile data takes too long to load"
+
+### Step 2: List Fundamental Truths
+
+What is absolutely true (not opinion or convention)?
+
+| Category | Examples |
+|----------|----------|
+| **Physical constraints** | Network latency ≥ 0, disk I/O has limits |
+| **Business rules** | "Users must see their own data" |
+| **Technical invariants** | "Data must be consistent" |
+| **User needs** | "The user wants X within Y seconds" |
+
+### Step 3: Challenge Assumptions
+
+For each component of the current plan:
+
+- **Fact or convention?** "We always use REST" — why?
+- **What if we removed this?** If nothing breaks, it's unnecessary.
+- **Solving the actual problem or a symptom?** Trace the causal chain.
+- **Who benefits from this complexity?** If "nobody", simplify.
+
+### Step 4: Build Up from Truths
+
+1. Start with the minimum viable mechanism satisfying all truths
+2. Add complexity only when a specific truth demands it
+3. Each addition must answer: "Which truth requires this?"
+
+### Step 5: Validate
+
+- Does the solution solve the original problem?
+- What assumptions need verification?
+- What's the simplest experiment to test this?
+
+## Requirement Convergence Gate
+
+Before final review, verify all of the following:
+
+- the user outcome and product value are explicit
+- in-scope and out-of-scope behavior are explicit
+- acceptance criteria describe observable outcomes
+- user-owned product, scope, UX, compatibility, and risk decisions are resolved
+- blocking open questions are empty
+- technical unknowns are researched or explicitly deferred without changing MVP behavior
+
+Lightweight tasks may skip slicing; they may not skip evidence inspection, requirement convergence, final review, or fresh implementation approval.
+
+The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
+
+## Artifact Rules
+
+`prd.md` records requirements and acceptance:
+
+- goal and user value
+- confirmed facts
+- requirements
+- acceptance criteria
+- out of scope
+- open questions that still block planning
+
+Technical design goes into `prd.md` under Technical Notes, or into `.atw/spec/` when it outlives the task. There is no separate design doc:
+
+- architecture and boundaries
+- data flow and contracts
+- compatibility and migration notes
+- important trade-offs
+- operational or rollback considerations
+
+Execution planning goes into tickets under `issues/`, written when the task is sliced. There is no separate plan doc:
+
+- ordered implementation checklist
+- validation commands
+- risky files or rollback points
+
+Lightweight tasks may have only `prd.md`. Work that spans more than one session is sliced into tickets before `task.py start`.
+
+Tickets are not a replacement for the JSONL context manifest. On sub-agent-dispatch workflows, `check.jsonl` must contain at least one real spec/research entry before `task.py start`; an empty manifest, or one holding only a legacy `_example` placeholder row, does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `atw-before-dev`.
+
+## PRD Convergence Pass
+
+Before declaring planning ready or running `task.py start`, rewrite `prd.md` once against the final structure described in the artifact rules above. This is not optional cleanup; it is the final planning gate.
+
+The pass must be lossless:
+
+- Collapse repeated facts into one authoritative section.
+- Fold temporary brainstorm sections such as `What I already know`, `Assumptions`, and resolved `Open Questions` into Goal, Background, Requirements, Technical Notes, or Acceptance Criteria.
+- Remove resolved open questions instead of leaving empty or already-answered sections.
+- Merge parallel bug and requirement lists when they describe the same work; keep each defect's severity, evidence, and file:line anchors on the owning requirement.
+- Preserve every file:line anchor, decision, constraint, requirement ID, and acceptance-criteria mapping.
+- Do not proceed to final review while any blocking open question remains.
+
+After the pass, read `prd.md` top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.
+
+## Quality Bar
+
+Before declaring planning ready:
+
+- `prd.md` contains testable acceptance criteria.
+- `prd.md` has passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings.
+- Repository-answerable questions have already been answered through inspection.
+- Blocking open questions are empty.
+- Work that spans more than one session is sliced into tickets under `issues/`.
+- Sub-agent-dispatch tasks have real curated entries in `check.jsonl`; a seed-only manifest is not ready.
+- The latest final planning summary has been presented to the user.
+- In a subsequent message, the user explicitly approved that summary for implementation.
+
+Do not start implementation merely because the user originally asked for implementation.