cowork-flow 0.0.1

package/src/lib/package-info.js

@@ -0,0 +1,49 @@
+import { execFile, spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { packageRoot } from './paths.js';
+
+const execFileAsync = promisify(execFile);
+
+export async function readPackageInfo() {
+  const raw = await readFile(join(packageRoot, 'package.json'), 'utf8');
+  return JSON.parse(raw);
+}
+
+export function compareVersions(left, right) {
+  const leftParts = left.split('.').map((part) => Number.parseInt(part, 10));
+  const rightParts = right.split('.').map((part) => Number.parseInt(part, 10));
+  const length = Math.max(leftParts.length, rightParts.length);
+
+  for (let index = 0; index < length; index += 1) {
+    const leftValue = Number.isFinite(leftParts[index]) ? leftParts[index] : 0;
+    const rightValue = Number.isFinite(rightParts[index]) ? rightParts[index] : 0;
+    if (leftValue < rightValue) {
+      return -1;
+    }
+    if (leftValue > rightValue) {
+      return 1;
+    }
+  }
+
+  return 0;
+}
+
+export async function fetchLatestVersion(packageName = 'cowork-flow') {
+  const result = await execFileAsync('npm', ['view', packageName, 'version'], {
+    encoding: 'utf8'
+  });
+  return result.stdout.trim();
+}
+
+export async function runGlobalInstall(packageSpec = 'cowork-flow@latest') {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn('npm', ['install', '-g', packageSpec], {
+      stdio: 'inherit'
+    });
+    child.on('error', rejectPromise);
+    child.on('close', (code) => resolvePromise(code ?? 1));
+  });
+}

package/src/lib/paths.js

@@ -0,0 +1,6 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const srcRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const packageRoot = resolve(srcRoot, '..');
+export const templateRoot = resolve(packageRoot, 'template');

package/template/.agent/skills/break-loop/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: break-loop
+description: Use when a bug has been fixed or repeated debugging attempts reveal a pattern that should be captured
+---
+
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this skill for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+
+---
+
+## Analysis Framework
+
+Analyze the bug you just fixed from these 5 dimensions:
+
+### 1. Root Cause Category
+
+Which category does this bug belong to?
+
+| Category | Characteristics | Example |
+|----------|-----------------|---------|
+| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
+| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
+| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
+| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
+| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
+
+### 2. Why Fixes Failed (if applicable)
+
+If you tried multiple fixes before succeeding, analyze each failure:
+
+- **Surface Fix**: Fixed symptom, not root cause
+- **Incomplete Scope**: Found root cause, didn't cover all cases
+- **Tool Limitation**: grep missed it, type check wasn't strict
+- **Mental Model**: Kept looking in same layer, didn't think cross-layer
+
+### 3. Prevention Mechanisms
+
+What mechanisms would prevent this from happening again?
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Documentation** | Write it down so people know | Update thinking guide |
+| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
+| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
+| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
+| **Test Coverage** | E2E tests, integration tests | Verify full flow |
+| **Code Review** | Checklist, PR template | "Did you check X?" |
+
+### 4. Systematic Expansion
+
+What broader problems does this bug reveal?
+
+- **Similar Issues**: Where else might this problem exist?
+- **Design Flaw**: Is there a fundamental architecture issue?
+- **Process Flaw**: Is there a development process improvement?
+- **Knowledge Gap**: Is the team missing some understanding?
+
+### 5. Knowledge Capture
+
+Solidify insights into the system:
+
+- [ ] Update `.cowork-flow/spec/guides/` thinking guides
+- [ ] Update `.cowork-flow/spec/backend/` or `frontend/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update `.cowork-flow/spec/` or workflow gates if needed
+
+---
+
+## Output Format
+
+Please output analysis in this format:
+
+```markdown
+## Bug Analysis: [Short Description]
+
+### 1. Root Cause Category
+- **Category**: [A/B/C/D/E] - [Category Name]
+- **Specific Cause**: [Detailed description]
+
+### 2. Why Fixes Failed (if applicable)
+1. [First attempt]: [Why it failed]
+2. [Second attempt]: [Why it failed]
+...
+
+### 3. Prevention Mechanisms
+| Priority | Mechanism | Specific Action | Status |
+|----------|-----------|-----------------|--------|
+| P0 | ... | ... | TODO/DONE |
+
+### 4. Systematic Expansion
+- **Similar Issues**: [List places with similar problems]
+- **Design Improvement**: [Architecture-level suggestions]
+- **Process Improvement**: [Development process suggestions]
+
+### 5. Knowledge Capture
+- [ ] [Documents to update / tickets to create]
+```
+
+---
+
+## Core Philosophy
+
+> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
+
+Three levels of insight:
+1. **Tactical**: How to fix THIS bug
+2. **Strategic**: How to prevent THIS CLASS of bugs
+3. **Philosophical**: How to expand thinking patterns
+
+30 minutes of analysis saves 30 hours of future debugging.
+
+---
+
+## After Analysis: Immediate Actions
+
+**IMPORTANT**: After completing the analysis above, you MUST immediately:
+
+1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
+   - If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
+   - If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
+   - If it's a code reuse issue → update `code-reuse-thinking-guide.md`
+   - If it's domain-specific → update `backend/*.md` or `frontend/*.md`
+   - If it's project-specific policy or commands → update `AGENTS.md`, `.cowork-flow/workflow.md`, or `.cowork-flow/config.yaml`
+
+2. **Do not edit reusable skills for project-specific lessons** - Skills should stay generic. Capture project facts in specs, config, workflow, or AGENTS instead.
+
+3. **Follow the project commit policy for the spec updates** - This is the primary output, not just the analysis text
+
+> **The analysis is worthless if it stays in chat. The value is in the updated specs.**

package/template/.agent/skills/check-cross-layer/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: check-cross-layer
+description: Use when reviewing changes that span layers, contracts, repeated patterns, or shared utilities
+---
+
+# Cross-Layer Check
+
+Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill.
+
+> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.cowork-flow/spec/guides/pre-implementation-checklist.md) **before** writing code.
+
+---
+
+## Related Documents
+
+| Document | Purpose | Timing |
+|----------|---------|--------|
+| [Pre-Implementation Checklist](.cowork-flow/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
+| [Code Reuse Thinking Guide](.cowork-flow/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation |
+| **`$check-cross-layer`** (this skill) | Verification check | **After** implementation |
+
+---
+
+## Execution Steps
+
+### 1. Identify Change Scope
+
+```bash
+git status
+git diff --name-only
+```
+
+### 2. Select Applicable Check Dimensions
+
+Based on your change type, execute relevant checks below:
+
+---
+
+## Dimension A: Cross-Layer Data Flow (Required when 3+ layers)
+
+**Trigger**: Changes involve 3 or more layers
+
+| Layer | Common Locations |
+|-------|------------------|
+| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` |
+| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` |
+| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` |
+| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` |
+| Utility | `utils/`, `helpers/`, `common/` |
+
+**Checklist**:
+- [ ] Read flow: Database -> Service -> API -> UI
+- [ ] Write flow: UI -> API -> Service -> Database
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+- [ ] Loading/pending states handled at each layer?
+
+**Detailed Guide**: `.cowork-flow/spec/guides/cross-layer-thinking-guide.md`
+
+---
+
+## Dimension B: Code Reuse (Required when modifying constants/config)
+
+**Trigger**: 
+- Modifying UI constants (label, icon, color)
+- Modifying any hardcoded value
+- Seeing similar code in multiple places
+- Creating a new utility/helper function
+- Just finished batch modifications across files
+
+**Checklist**:
+- [ ] Search first: How many places define this value?
+  ```bash
+  # Search in source files (adjust extensions for your project)
+  grep -r "value-to-change" src/
+  ```
+- [ ] If 2+ places define same value -> Should extract to shared constant
+- [ ] After modification, all usage sites updated?
+- [ ] If creating utility: Does similar utility already exist?
+
+**Detailed Guide**: `.cowork-flow/spec/guides/code-reuse-thinking-guide.md`
+
+---
+
+## Dimension B2: New Utility Functions
+
+**Trigger**: About to create a new utility/helper function
+
+**Checklist**:
+- [ ] Search for existing similar utilities first
+  ```bash
+  grep -r "functionNamePattern" src/
+  ```
+- [ ] If similar exists, can you extend it instead?
+- [ ] If creating new, is it in the right location (shared vs domain-specific)?
+
+---
+
+## Dimension B3: After Batch Modifications
+
+**Trigger**: Just modified similar patterns in multiple files
+
+**Checklist**:
+- [ ] Did you check ALL files with similar patterns?
+  ```bash
+  grep -r "patternYouChanged" src/
+  ```
+- [ ] Any files missed that should also be updated?
+- [ ] Should this pattern be abstracted to prevent future duplication?
+
+---
+
+## Dimension C: Import/Dependency Paths (Required when creating new files)
+
+**Trigger**: Creating new source files
+
+**Checklist**:
+- [ ] Using correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+- [ ] Consistent with project's module organization?
+
+---
+
+## Dimension D: Same-Layer Consistency
+
+**Trigger**: 
+- Modifying display logic or formatting
+- Same domain concept used in multiple places
+
+**Checklist**:
+- [ ] Search for other places using same concept
+  ```bash
+  grep -r "ConceptName" src/
+  ```
+- [ ] Are these usages consistent?
+- [ ] Should they share configuration/constants?
+
+---
+
+## Common Issues Quick Reference
+
+| Issue | Root Cause | Prevention |
+|-------|------------|------------|
+| Changed one place, missed others | Didn't search impact scope | `grep` before changing |
+| Data lost at some layer | Didn't check data flow | Trace data source to destination |
+| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions |
+| UI/output inconsistent | Same concept in multiple places | Extract shared constants |
+| Similar utility exists | Didn't search first | Search before creating |
+| Batch fix incomplete | Didn't verify all occurrences | grep after fixing |
+
+---
+
+## Output
+
+Report:
+1. Which dimensions your changes involve
+2. Check results for each dimension
+3. Issues found and fix suggestions

package/template/.agent/skills/finish-work/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: finish-work
+description: Use when finishing implementation work before handoff, submission, or project-defined commit
+---
+
+# Finish Work - Pre-Commit Checklist
+
+Before handoff, submission, or commit according to the project's policy, use this checklist to ensure work completeness.
+
+**Timing**: After code is written and tested, before final handoff or commit.
+
+---
+
+## Project Facts Source
+
+Do not edit this skill to replace commands or policy. Read project-specific facts from:
+
+1. `AGENTS.md` - test commands, commit policy, language and collaboration rules
+2. `.cowork-flow/workflow.md` - workflow gates and completion definition
+3. `.cowork-flow/config.yaml` - optional verification command lists
+4. `.cowork-flow/spec/` - project-specific implementation contracts
+
+If verification commands are listed in `.cowork-flow/config.yaml`, run them. If not, use the commands defined in `AGENTS.md` or infer the smallest relevant checks from the project files, then state the assumption.
+
+---
+
+## Checklist
+
+### 1. Code Quality
+
+- [ ] Read `AGENTS.md` and `.cowork-flow/config.yaml` for verification commands?
+- [ ] Static checks pass, if configured?
+- [ ] Build / type check pass, if configured?
+- [ ] Tests pass, if configured?
+- [ ] Temporary debug output removed?
+- [ ] Unsafe bypasses / force assertions reviewed?
+
+### 2. Code-Spec Sync
+
+**Code-Spec Docs**:
+- [ ] Does `.cowork-flow/spec/backend/` need updates?
+  - New patterns, new modules, new conventions, if backend specs exist
+- [ ] Does `.cowork-flow/spec/frontend/` need updates?
+  - New components, new hooks, new patterns, if frontend specs exist
+- [ ] Does `.cowork-flow/spec/guides/` need updates?
+  - New cross-layer flows, lessons from bugs, if guide specs exist
+
+**Key Question**: 
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?"
+
+If YES -> Update the relevant code-spec doc.
+
+### 2.5. Code-Spec Hard Block (Infra/Cross-Layer)
+
+If this change touches infra or cross-layer contracts, this is a blocking checklist:
+
+- [ ] Spec content is executable (real signatures/contracts), not principle-only text
+- [ ] Includes file path + command/API name + payload field names
+- [ ] Includes validation and error matrix
+- [ ] Includes Good/Base/Bad cases
+- [ ] Includes required tests and assertion points
+
+**Block Rule**:
+If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `$update-spec` manually first.
+
+### 2.6. Plan Sync
+
+If this task has a plan file in `.cowork-flow/plans/`:
+
+- [ ] Completed and verified plan steps are checked (`- [x]`)
+- [ ] Incomplete or blocked steps remain unchecked and are not falsely marked done
+- [ ] The plan's `Current Execution Status` (or equivalent section) reflects the latest verification / review / blocker state
+- [ ] Plan status matches the real task state before commit, archive, or completion claims
+
+### 3. API Changes
+
+If you modified API endpoints:
+
+- [ ] Input schema updated?
+- [ ] Output schema updated?
+- [ ] API documentation updated?
+- [ ] Client code updated to match?
+
+### 4. Database Changes
+
+If you modified database schema:
+
+- [ ] Migration file created?
+- [ ] Schema file updated?
+- [ ] Related queries updated?
+- [ ] Seed data updated (if applicable)?
+
+### 5. Cross-Layer Verification
+
+If the change spans multiple layers:
+
+- [ ] Data flows correctly through all layers?
+- [ ] Error handling works at each boundary?
+- [ ] Types are consistent across layers?
+- [ ] Loading states handled?
+
+### 6. Manual Testing
+
+- [ ] Feature works in browser/app?
+- [ ] Edge cases tested?
+- [ ] Error states tested?
+- [ ] Works after page refresh?
+
+---
+
+## Quick Check Flow
+
+```bash
+# 1. View changes
+git status
+git diff --name-only
+
+# 2. Run project verification commands from AGENTS.md or .cowork-flow/config.yaml
+
+# 3. Based on changed files, check relevant items above
+```
+
+---
+
+## Common Oversights
+
+| Oversight | Consequence | Check |
+|-----------|-------------|-------|
+| Code-spec docs not updated | Others don't know the change | Check .cowork-flow/spec/ |
+| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests |
+| Migration not created | Schema out of sync | Check migration directory |
+| Types/contracts not synced | Runtime errors | Check shared contract definitions |
+| Tests not updated | False confidence | Run full test suite |
+| Console.log left in | Noisy production logs | Search for console.log |
+| Plan checkboxes not synced | Docs drift from real progress | Check `.cowork-flow/plans/` before finishing |
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Write code -> Test -> $finish-work -> project commit/handoff policy -> $record-session
+                          |                                      |
+                   Ensure completeness                      Record progress
+                   
+Debug Flow:
+  Hit bug -> Fix -> $break-loop -> Knowledge capture
+                       |
+                  Deep analysis
+```
+
+- `$finish-work` - Check work completeness (this skill)
+- `$record-session` - Record session and completed work
+- `$break-loop` - Deep analysis after debugging
+
+---
+
+## Core Principle
+
+> **Delivery includes not just code, but also documentation, verification, and knowledge capture.**
+
+Complete work = Code + Docs + Tests + Verification

package/template/.agent/skills/record-session/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: record-session
+description: Use when recording completed work after verification and project commit or handoff policy has been satisfied
+---
+
+[!] **Prerequisite**: This skill should only be used AFTER verification is complete and business changes have been handled according to the project's commit / handoff policy, or when this is a planning / documentation-only session.
+
+Read `AGENTS.md` and `.cowork-flow/workflow.md` for the project's commit policy. The scripts below handle their own commits for `.cowork-flow/` metadata when git is available; do not use this skill to decide who commits business code.
+
+---
+
+## Record Work Progress
+
+### Step 0: Sync Plan Status First
+
+If the current task uses a plan file in `.cowork-flow/plans/`, update it before recording the session:
+
+- Check every completed and verified step as `- [x]`
+- Keep incomplete / blocked steps unchecked
+- Update the plan's current execution status with the latest review, verification, blocker, or handoff result
+
+Do not archive a task while the plan file still shows stale progress.
+
+### Step 1: Get Context & Check Tasks
+
+```bash
+python3 ./.cowork-flow/scripts/get_context.py --mode record
+```
+
+[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
+- Business changes handled per project policy? → Archive it
+- All acceptance criteria met? → Archive it
+- Don't skip archiving just because `status` still says `planning` or `in_progress`
+
+```bash
+python3 ./.cowork-flow/scripts/task.py archive <task-name>
+```
+
+### Step 2: One-Click Add Session
+
+```bash
+# Method 1: Simple parameters
+python3 ./.cowork-flow/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary of what was done"
+
+# Method 2: Pass detailed content via stdin
+cat << 'EOF' | python3 ./.cowork-flow/scripts/add_session.py --title "Title" --commit "hash"
+| Feature | Description |
+|---------|-------------|
+| Change | Description |
+|--------|-------------|
+| API | Updated endpoint contract |
+| UI | Synced client interaction |
+
+**Updated Files**:
+- `src/module/example-file.ext`
+- `docs/spec/example.md`
+EOF
+```
+
+**Auto-completes**:
+- [OK] Appends session to journal-N.md
+- [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
+- [OK] Auto-commits .cowork-flow/workspace and .cowork-flow/tasks changes when git is available
+
+---
+
+## Script Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `python3 ./.cowork-flow/scripts/get_context.py --mode record` | Get context for record-session |
+| `python3 ./.cowork-flow/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `python3 ./.cowork-flow/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
+| `python3 ./.cowork-flow/scripts/task.py list` | List active tasks |