@goodtek/vibeops 0.4.0 → 1.0.0

package/dist/lib/task.js

@@ -2,6 +2,7 @@ import { readdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import matter from "gray-matter";
 import { isDirectory, readText, writeText } from "./filesystem.js";
+import { readGitInfo } from "./git.js";
 const KNOWN_STATUSES = new Set([
     "planned",
     "in_progress",
@@ -32,7 +33,8 @@ export function statusDisplay(status) {
     }
 }
 function extractIdFromFilename(file) {
-    const m = /^(TASK-\d+)/i.exec(basename(file));
+    const name = basename(file);
+    const m = /^(TASK-\d+)/i.exec(name);
     return m ? m[1].toUpperCase() : basename(file, ".md");
 }
 function extractTitleFromBody(body) {
@@ -125,55 +127,71 @@ export function countTasks(tasks) {
         counts[t.status]++;
     return counts;
 }
+export function pickInProgressTask(tasks) {
+    return tasks.find((t) => t.status === "in_progress") ?? null;
+}
 export function pickNextTask(tasks) {
-    const inProgress = tasks.find((t) => t.status === "in_progress");
+    const inProgress = pickInProgressTask(tasks);
     if (inProgress)
         return inProgress;
     const review = tasks.find((t) => t.status === "review");
     if (review)
         return review;
-    const planned = tasks.find((t) => t.status === "planned");
-    return planned ?? null;
+    const planned = tasks.filter((t) => t.status === "planned");
+    return planned[0] ?? null;
+}
+const TEMPLATE_TASK_ID = "TASK-000";
+export function filterActionableTasks(tasks) {
+    return tasks.filter((t) => t.id.toUpperCase() !== TEMPLATE_TASK_ID);
+}
+function taskSortKey(id) {
+    const m = /^TASK-(\d+)$/i.exec(id.trim());
+    return m ? Number.parseInt(m[1], 10) : 0;
+}
+/** Latest finished TASK by numeric id (TASK-mvp sorts after numbered tasks). */
+export function pickLatestDoneTask(tasks) {
+    const done = filterActionableTasks(tasks).filter((t) => t.status === "done");
+    if (done.length === 0)
+        return null;
+    return [...done].sort((a, b) => taskSortKey(b.id) - taskSortKey(a.id))[0];
+}
+export async function loadActionableTasks(tasksDir) {
+    return filterActionableTasks(await scanTasks(tasksDir));
+}
+/** True when HEAD is on the TASK's recorded task branch. */
+export function isOnTaskBranch(gitBranch, ctx) {
+    return (typeof gitBranch === "string" &&
+        ctx !== null &&
+        gitBranch === ctx.taskBranch);
+}
+/**
+ * Prefer the TASK for the current `task/*` branch so `next` does not jump to the
+ * next Planned TASK while merge / `vibeops done` is still pending.
+ */
+export async function pickActiveTask(tasksDir, cwd) {
+    const actionable = await loadActionableTasks(tasksDir);
+    const git = await readGitInfo(cwd);
+    if (git.isRepo && typeof git.branch === "string" && git.branch.startsWith("task/")) {
+        for (const t of actionable) {
+            const ctx = await readGitContext(t.filePath);
+            if (isOnTaskBranch(git.branch, ctx))
+                return t;
+        }
+    }
+    return pickNextTask(actionable);
 }
 export async function findTaskFile(tasksDir, taskId) {
     const all = await scanTasks(tasksDir);
-    const target = taskId.toUpperCase();
+    const target = normalizeTaskRef(taskId);
     for (const t of all) {
         if (t.id.toUpperCase() === target)
             return t.filePath;
     }
     return null;
 }
-/**
- * Read the highest TASK number currently present in `tasksDir`.
- * Considers only filenames that match `TASK-NNN-*.md` (the `TASK-000-template.md`
- * scaffolding file is included — callers can subtract its `0` if they want to
- * skip the placeholder).
- *
- * Returns 0 if no TASK files exist or the directory is missing.
- */
-export async function highestTaskNumber(tasksDir) {
-    if (!(await isDirectory(tasksDir)))
-        return 0;
-    const entries = await readdir(tasksDir, { withFileTypes: true });
-    let max = 0;
-    for (const e of entries) {
-        if (!e.isFile() || !e.name.endsWith(".md"))
-            continue;
-        const m = /^TASK-(\d+)/i.exec(e.name);
-        if (!m)
-            continue;
-        const n = Number.parseInt(m[1], 10);
-        if (Number.isFinite(n) && n > max)
-            max = n;
-    }
-    return max;
-}
-export async function nextTaskNumber(tasksDir) {
-    return (await highestTaskNumber(tasksDir)) + 1;
-}
-export function formatTaskId(n, width = 3) {
-    return `TASK-${String(n).padStart(width, "0")}`;
+function normalizeTaskRef(ref) {
+    const t = ref.trim().toUpperCase();
+    return t.startsWith("TASK-") ? t : `TASK-${t}`;
 }
 const TASK_FILENAME_RE = /^TASK-(\d+)(?:-(.+))?$/i;
 export function parseTaskFilename(filePath) {
@@ -235,6 +253,18 @@ export function isPlaceholderContent(content) {
         return true; // legacy Korean placeholder
     if (/^_*\(none\)_*$/i.test(trimmed))
         return true;
+    if (/^\(not yet\)$/i.test(trimmed))
+        return true;
+    if (/^\(scaffold/i.test(trimmed))
+        return true;
+    if (/^pending\.?$/i.test(trimmed))
+        return true;
+    if (/^tbd\.?$/i.test(trimmed))
+        return true;
+    if (/^todo\.?$/i.test(trimmed))
+        return true;
+    if (/^-{1,3}$/.test(trimmed))
+        return true;
     return false;
 }
 export function hasNonEmptySection(body, title) {
@@ -306,6 +336,13 @@ export async function updateInlineStatus(filePath, next) {
         await writeText(filePath, updated);
     }
 }
+export async function updateTaskSection(filePath, title, content) {
+    const raw = await readText(filePath);
+    const updated = replaceSectionContent(raw, title, content);
+    if (updated !== raw) {
+        await writeText(filePath, updated);
+    }
+}
 function renderGitContextBlock(ctx) {
     const lines = [
         `- Base Branch: \`${ctx.baseBranch}\``,
@@ -325,8 +362,8 @@ export async function upsertGitContext(filePath, ctx) {
     if (locateSection(raw, "Git Context")) {
         updated = replaceSectionContent(raw, "Git Context", block);
     }
-    else if (locateSection(raw, "MVP Phase")) {
-        updated = insertSectionAfter(raw, "MVP Phase", "Git Context", block);
+    else if (locateSection(raw, "Test Plan")) {
+        updated = insertSectionAfter(raw, "Test Plan", "Git Context", block);
     }
     else if (locateSection(raw, "Status")) {
         updated = insertSectionAfter(raw, "Status", "Git Context", block);
@@ -345,6 +382,12 @@ const GIT_CTX_RE = {
     startedAt: /^-\s+Started At:\s*`([^`]+)`/m,
     doneAt: /^-\s+Done At:\s*`([^`]+)`/m,
 };
+export async function markGitContextDone(filePath) {
+    const ctx = await readGitContext(filePath);
+    if (ctx === null)
+        return;
+    await upsertGitContext(filePath, { ...ctx, doneAt: new Date().toISOString() });
+}
 export async function readGitContext(filePath) {
     const raw = await readText(filePath);
     const content = readSection(raw, "Git Context");

package/dist/types/config.js

@@ -1,17 +1 @@
 export const VIBEOPS_CONFIG_SCHEMA_VERSION = 1;
-export const DEFAULT_NOTION_CONFIG = {
-    enabled: false,
-    projectsTargetId: "",
-    tasksTargetId: "",
-    projectsDatabaseId: "",
-    tasksDatabaseId: "",
-};
-export const DEFAULT_GITHUB_CONFIG = {
-    enabled: false,
-    mode: "gh-cli",
-    owner: "",
-    repo: "",
-    remote: "origin",
-    visibility: "",
-    url: "",
-};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goodtek/vibeops",
-  "version": "0.4.0",
-  "description": "Workflow rails for Cursor-based vibe coding projects.",
+  "version": "1.0.0",
+  "description": "Minimal CLI rails for Cursor-based TASK-driven vibe coding.",
   "type": "module",
   "author": "VibeOps contributors",
   "license": "MIT",
@@ -35,13 +35,11 @@
     "coding",
     "cli",
     "task",
-    "notion",
     "vibeops",
     "workflow"
   ],
   "dependencies": {
     "@inquirer/prompts": "^8.4.3",
-    "@notionhq/client": "^5.20.0",
     "commander": "^12.1.0",
     "gray-matter": "^4.0.3"
   },
@@ -56,6 +54,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "start": "node dist/cli.js",
     "smoke": "pnpm typecheck && pnpm build && node scripts/smoke.mjs",
+    "clean": "rm -rf dist",
     "publish:dry": "pnpm publish --dry-run --no-git-checks"
   }
 }

package/templates/.cursor/rules/01-task-source-of-truth.mdc

@@ -0,0 +1,12 @@
+---
+description: TASK markdown is the execution source of truth; one TASK at a time
+alwaysApply: true
+---
+
+# TASK-driven work
+
+- Implement **one TASK** only (`docs/tasks/TASK-NNN-*.md`).
+- Read the **entire** current TASK file before changing code or docs.
+- Work only inside **Scope** and **Acceptance Criteria**.
+- Do not start another TASK id unless the human asks.
+- If chat and TASK docs disagree, **fix the docs first**, then implement.

package/templates/.cursor/rules/02-git-safety.mdc

@@ -0,0 +1,11 @@
+---
+description: Git safety for task branches and commits
+alwaysApply: true
+---
+
+# Git safety
+
+- Use branch pattern `task/*` created by `vibeops task add`.
+- Include the TASK id in commit messages, e.g. `feat(task-015): short title`.
+- **No force-push** to shared branches (`main`, `master`).
+- Do not merge or push unless the human runs `vibeops task done` or asks explicitly.

package/templates/.cursor/rules/03-docs-on-done.mdc

@@ -0,0 +1,13 @@
+---
+description: Update TASK Result and project memory when finishing work
+alwaysApply: true
+---
+
+# Docs when finishing a TASK
+
+Before `vibeops task done`:
+
+1. Fill **Result** and **Test Result** in the TASK file (paths, commands, outcomes — facts only).
+2. If architecture or decisions changed, note them in the TASK; `task done` updates `docs/project/*`.
+
+Do not mark a TASK complete with placeholder `(not yet)` sections.

package/templates/.cursor/skills/implement-task/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: implement-task
+description: Implements the current VibeOps TASK per Scope and Acceptance Criteria. Use when building features for docs/tasks/TASK-NNN.md.
+disable-model-invocation: true
+---
+
+# Implement a TASK
+
+## Read first
+
+1. `AGENTS.md` and `.cursor/rules/`
+2. `docs/project/05-current-state.md`, `03-architecture.md`, `06-decisions.md`
+3. The TASK file referenced by the human
+
+## Instructions
+
+1. Work **only** within Scope and Acceptance Criteria.
+2. Search the repo before adding files; match existing patterns.
+3. Fill **Result** and **Test Result** with facts when done.
+4. Do not run `vibeops task done` or merge — the human closes the TASK.
+
+Tell the human to run `vibeops task done TASK-NNN` when ready.

package/templates/.cursor/skills/plan-task/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: plan-task
+description: Refines a VibeOps TASK file (Goal, Scope, AC, Test Plan) via dialogue. Use when planning or editing docs/tasks/TASK-NNN.md before implementation.
+disable-model-invocation: true
+---
+
+# Plan a TASK
+
+The human opened a TASK file (e.g. `@docs/tasks/TASK-015-….md`).
+
+## Instructions
+
+1. Read the TASK file and `docs/project/05-current-state.md`.
+2. Ask only what is missing to make **Scope**, **Acceptance Criteria**, and **Test Plan** verifiable.
+3. Edit the TASK file in place — do not create a second TASK id.
+4. Keep **Out of Scope** explicit.
+5. Do not write application code in this step unless the human asks.
+
+When planning is enough, tell the human to switch to Agent mode and implement per the TASK.

package/templates/AGENTS.md

@@ -1,98 +1,37 @@
-# {{PROJECT_NAME}} — AI agent operating guide
+# {{PROJECT_NAME}} — AI agent guide
 
-> This file was installed by **VibeOps**. Every AI agent on this project (including Cursor) reads it before touching code.
-
-## Purpose
-
-This project runs **Cursor-based vibe coding** on rails. The execution input is **`docs/tasks/TASK-*.md`**, not chat history.
-
-## Required reading before you code
-
-Read the docs below **before you start implementing**. Order top to bottom.
-
-| Document                                   | Why                                                       |
-| ------------------------------------------ | --------------------------------------------------------- |
-| `docs/project/05-current-state.md`         | Where the project is today and what comes next             |
-| `docs/project/00-overview.md`              | Vision, terminology, MVP boundaries                       |
-| `docs/project/02-mvp-scope.md`             | What is in / out of MVP                                   |
-| `docs/project/03-architecture.md`          | System, folders, data flow                                |
-| `docs/project/04-tech-stack.md`            | Tools used to build the project                            |
-| `docs/project/06-decisions.md`             | Decisions already made (avoid conflicts)                   |
-| `docs/project/07-backlog.md`               | TASK order and definition of done                          |
-| **Current TASK file** `docs/tasks/TASK-NNN-*` | Scope and Acceptance Criteria for the current TASK     |
-
-`docs/project/01-requirements.md`, `08-env.md`, `09-deployment.md` are referenced as needed. **Always read the entire current TASK file.**
+> Installed by **VibeOps**. Cursor reads this repo, not chat history.
 
 ## Source of truth
 
-| What                       | Where                              |
-| -------------------------- | ---------------------------------- |
-| AI execution input         | Git `docs/tasks/*.md`              |
-| Project design and status  | Git `docs/project/*.md`            |
-| Change history and rollback | Git commits / branches            |
-| Human dashboard            | Notion (metadata only, never body) |
-| **Not** a source of truth  | Chat (Cursor history, Slack)       |
-
-## TASK-driven development rules
-
-1. Implement **one TASK at a time**.
-2. Stay inside the TASK's **Scope / Acceptance Criteria**.
-3. Before adding new code, **search** for existing implementations or patterns and avoid duplication.
-4. **Every mutating command** should support **`--dry-run`** (or an equivalent) so the plan can be previewed without side effects.
-5. **Large refactors** happen only when a dedicated TASK calls for them.
-6. **Notion / Git integrations** are only added when an explicit TASK assigns that responsibility.
-7. When the work is finished, update docs per [Completion report](#completion-report) and `.cursor/rules/04-docs-update.mdc`.
-
-Details live in `.cursor/rules/`.
-
-## Agent roles
-
-`.vibeops/agents/*.md` defines 8 agents for this project.
-
-- `orchestrator` — picks the next TASK and delegates to other agents.
-- `planner` — expands an idea into `docs/project/{00,01,02,07}`.
-- `architect` — fills in `docs/project/{03,04}` (architecture, tech stack).
-- `builder` — takes one TASK and edits code.
-- `reviewer` — compares the diff against the Acceptance Criteria.
-- `tester` — runs the Test Plan and fills in Test Result.
-- `docs` — updates `05-current-state.md`, the TASK Result, and `docs/logs/`.
-- `recovery` — diagnoses rollback options (destructive actions require `--confirm`).
-
-## Forbidden
-
-- Changing requirements or implementing things "loosely" based on chat alone.
-- Editing code or config **without reading the current TASK file**.
-- Mixing **multiple TASKs** in one session, or adding a large structure (e.g. `src/`) without a TASK.
-- Features **outside the TASK Scope** or **outside the MVP**.
-- Creating similar modules **without searching first**.
-- Performing **large refactors** without a dedicated TASK.
-- Adding **Notion / Git integration** that the TASK does not authorize.
-- Calling the TASK done without updating **`05-current-state.md` / the TASK file / `docs/logs/YYYY-MM-DD.md`**.
-
-## Cursor rule files
+| What | Where |
+|------|--------|
+| Current work | `docs/tasks/TASK-NNN-*.md` |
+| Project memory | `docs/project/05-current-state.md`, `03-architecture.md`, `06-decisions.md` |
+| Change history | Git commits on task branches |
+| **Not** trusted | Cursor chat, Slack |
 
-| File                                                  | Contents                                                  |
-| ----------------------------------------------------- | --------------------------------------------------------- |
-| `.cursor/rules/00-project-governance.mdc`             | Source of truth, one-TASK rule, MVP scope                  |
-| `.cursor/rules/01-agent-orchestration.mdc`            | Roles of the 8 agents and how they collaborate            |
-| `.cursor/rules/02-task-workflow.mdc`                  | How to start / run / finish a TASK, dry-run first         |
-| `.cursor/rules/03-git-safety.mdc`                     | Branch / rollback safety, no force-push                    |
-| `.cursor/rules/04-docs-update.mdc`                    | Mandatory doc updates after implementation                 |
+## Before you code
 
-## Completion report
+1. `docs/project/05-current-state.md`
+2. `docs/project/03-architecture.md` and `06-decisions.md` when relevant
+3. **The full current TASK file** under `docs/tasks/`
 
-When you finish a TASK, include at least the following in your chat response:
+## Workflow (human + CLI)
 
-1. **TASK ID** (for example `TASK-001`).
-2. **Summary** — 2 to 4 sentences on what was achieved.
-3. **Changed files** — list of the main paths.
-4. **Verification** — the commands you ran and their results.
-5. **Doc updates** — confirm you updated `05-current-state.md`, the TASK's Result / Test Result, and `docs/logs/YYYY-MM-DD.md`.
+```bash
+vibeops init              # once
+vibeops task add          # new TASK + branch
+# Plan in Cursor Ask: @docs/tasks/TASK-NNN-….md
+# Build in Cursor Agent: same file + Scope / Acceptance Criteria
+vibeops task done         # close TASK, update project docs, merge
+vibeops status            # briefing
+```
 
-Do not end the report with just "done".
+## Rules
 
-## VibeOps metadata
+- **One TASK at a time** — stay inside Scope and Acceptance Criteria.
+- **Search** before adding files; reuse existing patterns.
+- When the TASK is finished, **Result** and **Test Result** must be filled before `vibeops task done`.
 
-- Project name: `{{PROJECT_NAME}}`
-- Bootstrapped by: VibeOps `{{VIBEOPS_VERSION}}`
-- Created at: `{{CREATED_AT}}`
+Details: `.cursor/rules/`.

package/templates/docs/logs/README.md

@@ -1,38 +1,7 @@
-# Daily Logs
+# Daily logs
 
-This directory follows a **one-file-per-day** policy.
+Append-only files: `docs/logs/YYYY-MM-DD.md`.
 
-- Filename: `YYYY-MM-DD.md` (local date).
-- Create the file on the day's first change. Additional changes the same day append entries to the same file.
-- Logs are **fact-first**: decision summary, changed files, verification result, next work.
+`vibeops task done` may append a short entry when a TASK closes.
 
-## Entry template
-
-```
-## YYYY-MM-DD · TASK-NNN <short title>
-
-### Decision summary
-
-- ...
-
-### Changed files
-
-- new: ...
-- update: ...
-
-### Verification
-
-| Command | Result |
-| --- | --- |
-| `...` | ... |
-
-### Next work
-
-- TASK-NNN — ...
-```
-
-## Non-goals
-
-- Chitchat, opinions, self-praise.
-- Copy-pasted TASK bodies.
-- Secret values that should not be committed.
+Keep entries factual: TASK id, paths touched, commands run.

package/templates/docs/project/03-architecture.md

@@ -1,34 +1,15 @@
-# 03 — Architecture
+# Architecture
 
-> Filled in by the `architect` agent.
+> Living overview. Update when structure or major paths change (often via `vibeops task done`).
 
-## Big picture
+## System
 
-<!--
-Use an ASCII diagram to draw the "inside / outside the system" boundary.
-Flows like user → frontend → backend → DB / external services.
--->
+(describe stack and main folders as the project grows)
 
-## Components
+## Key paths
 
-<!--
-| Name        | Responsibility           | Inputs        | Outputs       |
-| ----------- | ------------------------ | ------------- | ------------- |
-| component-a | ...                      | ...           | ...           |
--->
-
-## Data model
-
-<!-- The 3 to 7 core entities and how they relate. Field-level detail belongs to a separate TASK. -->
-
-## Data flow
-
-<!-- The call sequence for the 1 to 2 most common user scenarios. -->
-
-## External boundaries
-
-<!-- Which external services / APIs we talk to. Auth method, public or private. -->
-
-## Non-deterministic / failure paths
-
-<!-- High-level behavior under network failures, concurrency, data loss. -->
+| Area | Path |
+|------|------|
+| Application | (TBD) |
+| TASK docs | `docs/tasks/` |
+| Project memory | `docs/project/` |

package/templates/docs/project/05-current-state.md

@@ -1,35 +1,15 @@
-# 05 — Current State
+# Current state
 
-> Record **facts only**. The `docs` agent refreshes this document after each implementation.
+> Facts only. Updated by `vibeops task done` and humans.
 
 ## Stage
 
-- **Current stage**: bootstrap complete. Planning and implementation have not started yet.
-- No code (`src/`, `package.json`, …) exists yet.
+- Bootstrapped with VibeOps. No TASK started yet.
 
-## What is in place
+## Active TASK
 
-| Item              | Location                              | Notes                       |
-| ----------------- | ------------------------------------- | --------------------------- |
-| Operating guide   | `AGENTS.md`, `.cursor/rules/*`        | Installed by VibeOps        |
-| Agent definitions | `.vibeops/agents/*`                   | 8 agents                    |
-| Project docs      | `docs/project/00 ~ 09`                | Empty (waiting for plan)    |
-| TASK folder       | `docs/tasks/`                         | Empty (waiting for generate) |
-| Logs folder       | `docs/logs/`                          | Empty                       |
+(none)
 
-## What is missing
+## Next step
 
-- The actual bodies of `docs/project/*` (planner / architect will fill these in).
-- `docs/tasks/TASK-001-*.md` (`task generate`).
-- Any code at all.
-- Notion connection (run `vibeops notion init` if desired).
-
-## Next TASK
-
-**The backlog is empty.** Run `vibeops plan --idea "<your idea>"` to fill in `docs/project/{00,01,02,07}`; the first TASK candidates fall out of that.
-
-## Working rules (short summary)
-
-- Implement **one TASK at a time**.
-- Every mutating command should support `--dry-run` when possible.
-- After implementation, update this document, the TASK file, and `docs/logs/YYYY-MM-DD.md` together.
+Run `vibeops task add` to create the first TASK.

package/templates/docs/project/06-decisions.md

@@ -1,20 +1,9 @@
-# 06 — Decisions
+# Decisions
 
-Decisions that have already been made. A conflicting proposal changes them only after a separate TASK reopens the discussion.
+> Append-only log. Add bullets when a TASK locks a choice — do not rewrite history.
 
-## D-001 · Source of truth is Git `docs/`
+## D-001 · VibeOps workflow
 
-Chat is not trusted. When docs and chat disagree, fix the docs first, then implement.
-
-## D-002 · One TASK at a time
-
-Large refactors do not happen without a dedicated TASK.
-
-## D-003 · Notion is the human dashboard (metadata only)
-
-No body sync. No realtime.
-
-<!--
-Add later decisions as `D-NNN · one-line summary`.
-Keep each entry short — one paragraph that covers "why" and "result".
--->
+- **Date:** {{CREATED_AT}}
+- **Decision:** TASK-driven development with `vibeops task add` / `task done` and Cursor for plan/build.
+- **Why:** Git `docs/tasks` beats chat as source of truth.