@goodtek/vibeops 0.2.0

package/templates/.vibeops/workflows/project-start.md

@@ -0,0 +1,73 @@
+# Workflow · Project Start
+
+The first hour of a new project.
+
+## 0. Prepare
+
+- Start in an empty directory.
+- The user has a one-to-two-paragraph **idea**.
+
+## 1. Bootstrap
+
+```bash
+vibeops init --name <project-name>
+git init && git add . && git commit -m "chore: bootstrap vibeops"
+```
+
+What gets created:
+- `AGENTS.md`, `.cursor/rules/*`, `docs/project/*`, `docs/tasks/`, `docs/logs/`
+- `.vibeops/agents/*`, `.vibeops/prompts/*`, `.vibeops/workflows/*`
+- `.vibeops.json`, `.vibeops.env.example`
+
+## 2. Plan
+
+```bash
+vibeops plan --idea "<one-paragraph idea>"
+```
+
+Paste the resulting prompt into Cursor. Cursor takes on the `planner` agent role and fills in four files.
+
+- `docs/project/00-overview.md`
+- `docs/project/01-requirements.md`
+- `docs/project/02-mvp-scope.md`
+- `docs/project/07-backlog.md`
+
+Next, invoke `architect` to fill in `03-architecture.md` and `04-tech-stack.md`.
+
+## 3. Backlog → TASKs
+
+For each backlog item:
+
+```bash
+vibeops task generate --from-backlog TASK-NNN
+```
+
+A `docs/tasks/TASK-NNN-*.md` file appears.
+
+## 4. First TASK
+
+```bash
+vibeops task start TASK-001
+vibeops task prompt TASK-001 --agent builder
+# paste into Cursor and let it work
+vibeops task check TASK-001
+vibeops task done TASK-001
+```
+
+Read the merge guidance, then merge and push manually.
+
+## 5. (Optional) Notion
+
+```bash
+vibeops notion init      # interactive .vibeops.env setup
+vibeops notion test      # validate API access and DB schemas
+vibeops notion sync      # push docs/tasks metadata to Notion
+```
+
+## 6. Daily
+
+```bash
+vibeops status           # check where you are in one second
+```
+
+Add one entry per decision or step to `docs/logs/YYYY-MM-DD.md` each day.

package/templates/.vibeops/workflows/rollback.md

@@ -0,0 +1,45 @@
+# Workflow · Rollback
+
+The standard "this TASK went wrong, let's undo it" flow.
+
+## 1. Diagnose first
+
+```bash
+vibeops task rollback TASK-NNN
+```
+
+The default is **guidance only**. It shows:
+
+- Current branch / dirty state.
+- Base branch / base commit / task branch as read from `.vibeops/state/tasks/TASK-NNN.json`.
+- Three possible strategies.
+
+## 2. Available strategies
+
+| Strategy          | Description                                                  | What you could lose                  |
+| ----------------- | ------------------------------------------------------------ | ------------------------------------ |
+| `branch-delete`   | Discard the task branch                                      | Every unmerged change on the branch  |
+| `reset-base`      | Hard-reset the current branch to the base commit              | Your current changes (stash first)   |
+| `revert-merge`    | If already merged, revert the merge commit                    | Adds a revert commit to history (OK) |
+
+## 3. Execute (destructive, `--confirm` required)
+
+```bash
+vibeops task rollback TASK-NNN --strategy branch-delete --confirm
+vibeops task rollback TASK-NNN --strategy reset-base --confirm
+vibeops task rollback TASK-NNN --strategy revert-merge --confirm
+```
+
+Combining `--dry-run` with `--confirm` prints the commands that would run without executing them.
+
+## 4. Things you never do
+
+- **`git push --force`**: never on shared branches. Even on your own task branch, do not run it unless the reason is unambiguous.
+- Automatic reflog cleanup.
+- Dropping stashes without explicit user consent.
+
+## 5. After rollback
+
+- Reset `docs/tasks/TASK-NNN-*.md` Status to `planned` or `blocked` and record the reason in Result.
+- Update `docs/project/05-current-state.md`.
+- Append a one-line entry to `docs/logs/YYYY-MM-DD.md`: "Rollback: TASK-NNN — reason".

package/templates/.vibeops/workflows/task-lifecycle.md

@@ -0,0 +1,71 @@
+# Workflow · Task Lifecycle
+
+A TASK from start to finish.
+
+## 0. Pick
+
+Run `vibeops status` to identify the next TASK. Typically run `in_progress` items before `planned` ones.
+
+## 1. Start
+
+```bash
+vibeops task start TASK-NNN
+```
+
+- A dirty working tree is refused (override with `--allow-dirty`, not recommended).
+- Records base branch / base commit / task branch in `.vibeops/state/tasks/TASK-NNN.json`.
+- Creates and checks out the `task/NNN-<slug>` branch.
+- Sets the TASK file's Status to `in_progress`.
+
+## 2. Prompt
+
+```bash
+vibeops task prompt TASK-NNN --agent builder
+```
+
+Paste the single markdown output directly into the Cursor chat. Cursor takes on the builder agent role.
+
+Other agents work the same way:
+- `--agent reviewer` — review the diff.
+- `--agent tester` — run the Test Plan.
+- `--agent docs` — update the three docs.
+
+## 3. Check
+
+```bash
+vibeops task check TASK-NNN
+```
+
+- Score Acceptance Criteria items with ✓ / ✗.
+- Match `Expected Files to Change` against actual changes.
+- Summarize current branch / dirty / commit count.
+
+## 4. Done
+
+```bash
+vibeops task done TASK-NNN
+```
+
+- Validates the TASK file's Status, Result, Test Result bodies.
+- Records `doneAt` in `.vibeops/state/tasks/TASK-NNN.json`.
+- Prints **merge guidance** (no automatic merge).
+
+A human merges:
+
+```bash
+git switch main
+git merge --ff-only task/NNN-<slug>
+git branch -d task/NNN-<slug>
+```
+
+## 5. (Optional) Notion sync
+
+```bash
+vibeops notion sync
+```
+
+Pushes TASK metadata (summary, status, priority, branch, docs path, result summary) to Notion.
+
+## When things go wrong: Rollback
+
+See [`rollback.md`](rollback.md).

package/templates/AGENTS.md

@@ -0,0 +1,98 @@
+# {{PROJECT_NAME}} — AI agent operating 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.**
+
+## 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
+
+| 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                 |
+
+## Completion report
+
+When you finish a TASK, include at least the following in your chat response:
+
+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`.
+
+Do not end the report with just "done".
+
+## VibeOps metadata
+
+- Project name: `{{PROJECT_NAME}}`
+- Bootstrapped by: VibeOps `{{VIBEOPS_VERSION}}`
+- Created at: `{{CREATED_AT}}`

package/templates/docs/logs/README.md

@@ -0,0 +1,38 @@
+# Daily Logs
+
+This directory follows a **one-file-per-day** policy.
+
+- 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.
+
+## 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.

package/templates/docs/project/00-overview.md

@@ -0,0 +1,27 @@
+# 00 — Overview
+
+> This document is the slot that `vibeops plan` (via the `planner` agent) fills in. Keep the section headers below and leave the bodies empty.
+
+## One-line definition
+
+<!-- One sentence describing what this project is — who it is for and what the tool/service does. -->
+
+## Problem to solve
+
+<!-- 3 to 5 bullets. Stay fact-based about current pain points. -->
+
+## Example usage
+
+<!-- A 6-to-10-line scenario showing how a single hypothetical user flows through the product. -->
+
+## Core roles
+
+<!-- 4 to 8 things this product "does", one per line. Each line starts with a verb. -->
+
+## Vocabulary
+
+<!-- 5 to 10 terms that mean something specific in this project. Disambiguate synonyms. -->
+
+## Non-goals (out of scope, forever)
+
+<!-- Things this project intentionally does not do. Different from "out of MVP scope" — that lives in 02-mvp-scope.md. -->

package/templates/docs/project/01-requirements.md

@@ -0,0 +1,30 @@
+# 01 — Requirements
+
+> Filled in by the `planner` agent.
+
+## Functional requirements
+
+<!--
+Numbered. Each line reads "the system does …".
+F-001. Users can ...
+F-002. The system ...
+-->
+
+## Non-functional requirements
+
+<!--
+Performance / reliability / security / operations / compatibility.
+NF-001. No command may corrupt user data ...
+-->
+
+## Users / stakeholders
+
+<!-- Who uses the product, who cares about it. By role. -->
+
+## Constraints
+
+<!-- Technical, schedule, budget, regulatory — anything imposed from outside. -->
+
+## Assumptions
+
+<!-- The "let's assume this is true" list. Items that would be risky if they break. -->

package/templates/docs/project/02-mvp-scope.md

@@ -0,0 +1,36 @@
+# 02 — MVP Scope
+
+> Filled in by the `planner` agent. Keep it small.
+
+## MVP in one sentence
+
+<!-- A single line: "Within two weeks, who can do what." -->
+
+## In scope
+
+<!--
+The 5 to 10 capabilities the MVP must have.
+- IN: sign-up and single sign-on
+- IN: ...
+-->
+
+## Intentionally out for MVP
+
+<!--
+Things that may ship later but not in the MVP.
+- OUT: multiple workspaces
+- OUT: payment UI
+The clearer this is, the smaller the backlog gets.
+-->
+
+## Definition of done
+
+<!--
+- Which scenarios run end-to-end.
+- Which data flows are preserved.
+- Which error situations are tolerated.
+-->
+
+## How to validate
+
+<!-- How a real person confirms "the MVP is ready". One demo scenario. -->

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

@@ -0,0 +1,34 @@
+# 03 — Architecture
+
+> Filled in by the `architect` agent.
+
+## Big picture
+
+<!--
+Use an ASCII diagram to draw the "inside / outside the system" boundary.
+Flows like user → frontend → backend → DB / external services.
+-->
+
+## Components
+
+<!--
+| 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. -->

package/templates/docs/project/04-tech-stack.md

@@ -0,0 +1,29 @@
+# 04 — Tech Stack
+
+> Filled in by the `architect` agent. Add a one-line "why" to each choice.
+
+## Runtime / language
+
+<!-- Node.js / Python / Go, etc. Version. The reason behind the choice. -->
+
+## Frameworks / libraries
+
+<!--
+| Area    | Choice             | Why                                            |
+| ------- | ------------------ | ---------------------------------------------- |
+| Server  | ...                | ...                                            |
+| ORM     | ...                | ...                                            |
+| Tests   | vitest             | TS-friendly, fast                              |
+-->
+
+## Infrastructure
+
+<!-- Where the system runs, how it is deployed (high level). Detailed commands live in 09-deployment.md. -->
+
+## Package manager / build
+
+<!-- pnpm / npm / yarn, tsc / esbuild / vite, etc. Whether there is a single entry point. -->
+
+## Explicit non-adoptions
+
+<!-- Things we deliberately do not use, and why. -->

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

@@ -0,0 +1,35 @@
+# 05 — Current State
+
+> Record **facts only**. The `docs` agent refreshes this document after each implementation.
+
+## Stage
+
+- **Current stage**: bootstrap complete. Planning and implementation have not started yet.
+- No code (`src/`, `package.json`, …) exists yet.
+
+## What is in place
+
+| 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                       |
+
+## What is missing
+
+- 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.

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

@@ -0,0 +1,20 @@
+# 06 — Decisions
+
+Decisions that have already been made. A conflicting proposal changes them only after a separate TASK reopens the discussion.
+
+## D-001 · Source of truth is Git `docs/`
+
+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".
+-->

package/templates/docs/project/07-backlog.md

@@ -0,0 +1,23 @@
+# 07 — Backlog
+
+TASK order. Work top to bottom. Do not skip to the next item before the current TASK is done.
+
+> Slot to be filled by the `planner` agent.
+
+## MVP 1
+
+| ID       | Title                               | Status  |
+| -------- | ----------------------------------- | ------- |
+| TASK-001 | <first TASK title>                  | planned |
+
+## MVP 2 (later)
+
+<!-- Slot. -->
+
+## Later (out of MVP, but live candidates)
+
+<!-- Items to revisit after MVP. Do not turn them into TASKs right away. -->
+
+## Non-goals
+
+Follow the "Non-goals" section in `docs/project/00-overview.md`. The backlog only grows inside those bounds.

package/templates/docs/project/08-env.md

@@ -0,0 +1,29 @@
+# 08 — Environment
+
+Environment variables used by this project and what they mean.
+
+## Local development
+
+Copy `.vibeops.env.example` to `.vibeops.env` and fill in the values. Never commit `.vibeops.env` — it is listed in `.gitignore`.
+
+| Variable        | Purpose                                                          | Required        |
+| --------------- | ---------------------------------------------------------------- | --------------- |
+| `NOTION_TOKEN`  | Notion internal integration secret (the only secret VibeOps reads) | If using Notion |
+
+`NOTION_TOKEN` is the only secret VibeOps reads from the environment. Notion **Projects / Tasks DB target IDs** are not environment variables — they live in `.vibeops.json` as `notion.projectsTargetId` / `notion.tasksTargetId`, and `vibeops notion init` writes them. GitHub auth is owned by `gh auth`, so there is no need to put `GITHUB_TOKEN` here.
+
+> The legacy `NOTION_API_KEY` / `NOTION_PROJECT_DB` / `NOTION_TASK_DB` environment variables are no longer used. VibeOps ignores them if they remain in an existing `.vibeops.env`. It is safe to remove them by hand.
+
+<!--
+Add project-specific environment variables here once they exist.
+Examples: DATABASE_URL, OAUTH_CLIENT_ID, ...
+-->
+
+## Staging / production
+
+<!-- Slot. -->
+
+## Secret management
+
+- `.vibeops.env` is a plain-text local file. Production secrets belong in a real secret manager.
+- No VibeOps command prints secret values to stdout in the clear (they are masked).

package/templates/docs/project/09-deployment.md

@@ -0,0 +1,28 @@
+# 09 — Deployment
+
+How the project is deployed and run.
+
+## Local run
+
+<!-- The single-command dev-server flow (e.g. `pnpm dev`). -->
+
+## Build
+
+<!-- Where build artifacts live and which command produces them. -->
+
+## Packaging / release
+
+<!--
+Steps per target environment.
+- npm publish?
+- Docker image?
+- Cloud (Vercel / Fly / AWS / GCP / ...) ?
+-->
+
+## Environment separation
+
+<!-- Differences between dev / staging / prod. Same code with different env? Same image? -->
+
+## Rollback
+
+<!-- The standard rollback flow when a deployment goes wrong. -->