How the NepWalk Workflow Works

This document explains the full system — how repos are structured, how AI tools are used, how departments hand off to each other, and what commands to type.

The two-repo rule

Every team member clones exactly two repos:

~/code/nepwalk/
  nepwalk-docs/       ← shared knowledge. Read inputs from here. Publish outputs here.
  nepwalk-<dept>/     ← your dept's AI config. This is where you work.

nepwalk-docs is the single source of truth. All documents — specs, designs, test plans, marketing strategy — live here. No team member writes docs anywhere else.

nepwalk-<dept> contains only AI configuration: dept.yaml (what to read, what to write), AGENTS.md (rules for the AI), skills, and specialist agents. It has no documents of its own.

How departments are ordered

Work flows in one direction. Each dept depends on the outputs of the dept above it.

Management  →  produces: idea, PRD, SRS, user stories, roadmap,
                          task division, acceptance criteria, dependency map
     ↓
Design      →  reads: PRD + user stories + task division + dependency map
             →  produces: design system, component catalog, page specs
     ↓
Frontend    →  reads: SRS + design system + component catalog + page specs + task division + dependency map
Backend     →  reads: SRS + task division + dependency map
     ↓
QA          →  reads: SRS + user stories + API spec + acceptance criteria + task division + dependency map
     ↓
Marketing   →  reads: PRD + idea (can start in parallel)
Research    →  reads: any open questions (can start in parallel)

Marketing and Research can run in parallel at any time. All other depts are sequential — you cannot start design without a PRD, you cannot start frontend without a design system.

The AI enforces this. If required inputs are missing, it warns you before you start a task.

Setup (one time)

1. Clone the two repos

mkdir -p ~/code/nepwalk && cd ~/code/nepwalk
git clone <nepwalk-docs-url> nepwalk-docs
git clone <nepwalk-<dept>-url> nepwalk-<dept>
```text

The sibling layout is required. `dept.yaml` uses relative paths like `../nepwalk-docs/docs/`.

> **Windows users:** The setup scripts (`.sh` files) require a Unix shell. Use **Git Bash** (comes with [Git for Windows](https://git-scm.com/)) or **WSL** (Windows Subsystem for Linux). PowerShell and CMD will not work. Open Git Bash from the Start menu, then run all `bash` commands there. Once setup is done, your AI tool (Claude Code, OpenCode, Codex) works normally in any terminal.

### 2. Sync canonical files

```bash
cd nepwalk-<dept>
./scripts/sync-from-docs.sh

This pulls the latest skills and specialist agents from nepwalk-docs and regenerates PROJECT_STATE.md.

3. MCP docs server (automatic)

A global MCP filesystem server is configured at ~/.claude/.mcp.json. It serves nepwalk-docs/docs/ read-only to all AI sessions. This means:

The AI can read any doc from nepwalk-docs on demand via MCP tools
Only requested files are loaded — saves tokens vs reading everything upfront
No manual file paths needed — the AI queries the MCP server directly

The server starts automatically when a Claude Code session opens. No per-department setup required.

4. Open in your AI tool

Open the nepwalk-<dept> folder in Claude Code, OpenCode, or Codex. The tool reads AGENTS.md automatically. The AI is now configured for your department.

The session loop

Every working session follows this loop.

Step 1 — Check status

<dept>_status:

The AI reads dept.yaml and PROJECT_STATE.md and reports:

INPUTS
  [x] nepwalk-docs/management/mvp/prd_v1.md — approved
  [ ] nepwalk-docs/management/mvp/user_story_v1.md — MISSING

PREREQUISITE DOCS
  [ ] design/mvp/design_system.md — not started
  [ ] design/mvp/component_catalog.md — not started

TASKS
  1. Create design system
  2. Create component catalog
  3. Home page spec — unclaimed

BLOCKED: user_story_v1.md missing. Notify management.

Step 2 — Handle blockers first

If required inputs are missing, notify the upstream department. Don't proceed past the prerequisite gate without them.

If you want to proceed anyway: the AI will ask Proceed anyway? (yes / no). Type yes and it will continue with a warning in PROJECT_STATE.md.

Step 3 — Create prerequisite docs (first session only)

If this is the first session and required output docs don't exist yet:

<dept>: init-docs

The AI creates all required_before_work documents from templates in one shot. These are created as status: draft in nepwalk-docs/docs/<dept>/mvp/.

Step 4 — Pick a task

<dept>: tasks

The AI reads the SRS/PRD, compares against existing output files, and lists what remains.

Step 5 — Work a task

<dept>: start <task-name>

The AI runs the prerequisite gate, loads relevant context from nepwalk-docs, and begins work. Output goes directly to nepwalk-docs/docs/<dept>/mvp/ as status: draft.

Step 6 — Publish when ready

<dept>: publish <filename>

Promotes the document from status: draft to status: review and opens a PR to nepwalk-docs. A reviewer approves it, which changes status to approved. Downstream depts can then use it as an input.

Step 7 — Update state

state:

Regenerates PROJECT_STATE.md from the current file state. Run this at the end of a session or after any major change.

Prefix command reference (all depts)

Command	What it does
`<dept>_status:`	Show input/output/task status. Safe to run anytime.
`<dept>: tasks`	List unclaimed tasks from SRS/PRD vs existing output files.
`<dept>: init-docs`	Create all prerequisite docs from templates. First session only.
`<dept>: start <task>`	Begin a task — gate check, load context, create branch.
`<dept>: publish <file>`	Promote draft → review, open PR.
`<dept>: agent <slug> <task>`	Dispatch a specialist agent for deep work.
`tasks: [context]`	Generate task division with AI + human tracks. Management only.
`acceptance: [context]`	Generate acceptance criteria checklist. Management only.
`deps: [context]`	Generate cross-department dependency map. Management only.
`state:`	Regenerate `PROJECT_STATE.md`. Shows human task alerts first.

Specialist agents

Each dept has a roster of specialist agents (defined in dept.yaml → agents:). These are focused personas from the agency-agents library — a UI designer, a backend architect, a QA automation engineer, etc.

Dispatch one when you need deep specialist work:

design: agent design-ui-designer "design the trip card component"

The agent runs in caveman mode and writes its output to the path declared in dept.yaml. The dept's main AI remains the orchestrator — the specialist handles one focused task.

Agents work in any tool: Claude Code (.claude/agents/), OpenCode (.opencode/agents/), Codex (.codex/agents/).

Document status lifecycle

Every document in nepwalk-docs goes through three statuses:

Status	Meaning	Who can set it
`draft`	Created, being worked on	AI (automatically on creation)
`review`	Ready for human review	AI via `<dept>: publish`
`final`	Confirmed correct, frozen, safe to use as input	Human reviewer

Downstream departments should only treat final documents as reliable inputs. draft and review documents can change.

Full status definitions: docs/guidelines/status_definitions.md

Multi-person frontend / backend

When multiple people work in the same dept repo, divide tasks before starting:

frontend: divide tasks 3

The AI reads the SRS, splits frontend work into 3 non-overlapping tracks, and writes nepwalk-docs/docs/frontend/mvp/task_division.md.

Each person claims a track:

frontend: claim track-a

The AI updates task_division.md (name + timestamp) and scopes the session to that track only. PROJECT_STATE.md shows only claimed tasks going forward.

Each task gets its own branch:

frontend: start dashboard
→ creates branch feat/dashboard

No two people touch the same files at the start of a task. If tracks need to merge shared code, that happens via a normal PR review.

Keeping in sync

Canonical skills and schemas live in nepwalk-docs. When they update, sync your dept repo:

./scripts/sync-from-docs.sh
git diff    # review what changed
git add . && git commit -m "chore: sync from nepwalk-docs"
```text

The sync script also updates specialist agent files if the agent roster in `dept.yaml` has changed.

---

## PR ordering rule

For every feature task, the department follows this sequence:

1. **Docs PR first** — submit a PR to `nepwalk-docs` with the spec, design, or test plan for the work.
2. **Docs PR merged** — reviewer approves, status moves to `approved`.
3. **Code PR second** — submit a PR to the code repo (backend, frontend) implementing the approved spec.
4. **Code PR merged** — reviewer approves after verifying it matches the spec.
5. **Downstream unblocked** — dependent departments may now start their work.

Both PRs (docs + code) from the upstream department must be merged before a dependent department begins its task. The AI warns if upstream PRs are not merged but does not block.

---

## Task completion: AI + human tracks

Every task has two tracks that both must complete:

- **AI work** — what the AI builds, generates, or tests autonomously.
- **Human task** — work that AI cannot do. Examples: add API keys (Claude, Google, Supabase), configure database URLs, set up OAuth credentials, create third-party service accounts, test on a real device, review and approve PRs, verify deployed environments.

If a track is skipped, the user must explicitly say "skip" and provide a reason. The skip is recorded in `task_division` and `PROJECT_STATE.md` so other departments can see it.

### Human task alerts

When any department runs `status:`, all pending human tasks are shown first as alerts:

```text
⚠️ HUMAN TASKS REQUIRED
  [ ] T-003: Add Claude API key to .env
  [ ] T-007: Create Supabase project and set DATABASE_URL

These tasks block dependent AI work. Complete them or skip with a reason.

This ensures the user always knows what they need to do before AI can proceed.

Per-department task and acceptance docs

Management creates task_division and acceptance_criteria docs at two levels:

Cross-department overview — lives in docs/management/mvp/. Read-only for all other departments. Shows the full picture.
Per-department detail — lives in docs/<dept>/mvp/. Created by management, but the department can update it as work progresses (mark tasks done, update statuses, add details, record skips).

docs/management/mvp/v1/task_division_v1.md     ← overview (read-only for depts)
docs/backend/mvp/v1/task_division_v1.md        ← backend's copy (read-write for backend)
docs/frontend/mvp/v1/task_division_v1.md       ← frontend's copy (read-write for frontend)
docs/design/mvp/v1/task_division_v1.md         ← design's copy (read-write for design)
docs/qa/mvp/v1/task_division_v1.md             ← QA's copy (read-write for QA)

Same pattern for acceptance_criteria_v1.md. The dependency_map is cross-department only — no per-department copies.

Versioned folder structure

All docs are placed in a folder matching their major version:

docs/management/mvp/v1/          ← all v1 docs (idea, PRD, SRS, etc.)
docs/management/mvp/v2/          ← all v2 docs (if a new major version is created)
docs/backend/mvp/v1/             ← backend's v1 task_division and acceptance_criteria

Minor versions (v1.1, v1.2) stay in the same major version folder. A new major version creates a new folder.

When a department updates its own task_division or acceptance_criteria, it submits a PR to nepwalk-docs. Management can see all updates across departments.

Keeping this document up to date

Any change that affects how departments work must also update this document. This includes: new prefix commands, new doc types, changed PR rules, new task tracks, updated dependency flows, or architecture changes.

Rule: If a session changes workflow or architecture, update this file in the same session. This document is the single reference for how to run the NepWalk system.

What the AI never does

Creates documents outside nepwalk-docs/docs/<dept>/ (no local drafts)
Promotes a document to approved (human-only)
Starts a task without running the prerequisite gate
Edits another dept's output files directly
Assumes a skip — user must explicitly say "skip"