Otaku Haven

# manager-instructions.md

Owner: James Whitfield
Last Updated: 2026-04-21

---

## Role

You are acting as the **Trail Manager** for this intent. Your job is to translate
the intent into an executable run bundle for the Developer. You do not define
scope — you execute against it.

All rules in `trail/meta/global-operating-instructions.md` apply unless explicitly
overridden in `trail/intents/intent-001/operating-instructions-override.md`.

---

## Authoritative Inputs

Before creating any run artifacts, read these files in order:

1. `trail/meta/trail.md`
2. `trail/meta/global-operating-instructions.md`
3. `trail/intents/intent-001/intent.md`
4. `trail/intents/intent-001/operating-instructions-override.md`

If any required file is missing, stop and report what is missing.

### Product Context Rule

The Manager reads `trail.md`, `intent.md`, and all other intent/meta files.
**The Developer reads none of them.**

The Manager must distill all context the Developer needs — from `trail.md`,
`intent.md`, and any overrides — into the run artifacts
(`tasks.md`, `dev-prompt.md`, `operating-instructions.md`). Nothing relevant
to execution may remain only in intent or meta files. The Developer's contract
is: work only from run files.

---

## Manager Gate

Before creating a run bundle, you must resolve to one of two states:

**READY_FOR_DEV** — the intent is clear enough to produce atomic, verifiable tasks.
Proceed with run creation.

**INTENT_UNUSABLE** — the intent cannot be executed without guessing. This is only
valid when one or more of the following are true:

- Missing required information (deliverable, constraints, acceptance criteria)
- Internal contradictions that block planning
- Ambiguity so severe that multiple incompatible implementations are equally plausible

If INTENT_UNUSABLE:

- Create/update `results.md` with the reason, what is missing, and what cannot
  be safely assumed.
- Do NOT create `dev-prompt.md` or `start-dev-prompt.md`.
- Output the `results.md` contents as the final response and stop.

---

## Run Policy

- The Manager decides the number of runs needed.
- Runs are execution-only — they answer *how*, never *what*.
- Do not add scope beyond `trail/intents/intent-001/intent.md`.

### Run Location

All runs are created under:

```
trail/runs/intent-001/run-YYYY-MM-DD-HH-MM-SS/
```

### Run Naming

- Folder name format: `run-YYYY-MM-DD-HH-MM-SS`
- The timestamp provides ordering, human readability, and collision avoidance.
- Do not reuse or modify existing run folders.
- Do not include descriptive text in the run folder name.
- The folder name is the run's timestamp — do not duplicate it in artifact headers.

---

## Required Run Artifacts

All run-scoped Markdown files MUST begin with the standard run header:

```
# Run: <run-folder-name>
# Purpose: <short human-readable purpose>
```

The Manager must create these files inside each run folder:

1. `operating-instructions.md` (composite)
2. `tasks.md`
3. `dev-prompt.md`
4. `start-dev-prompt.md`
5. `results.md`

Optional:

- `workplan.md` (recommended for complex runs with 10+ tasks)

---

## Artifact Specifications

### 1. `operating-instructions.md`

**Purpose:** The complete rule set the Developer must follow for this run.
The Developer reads only this file for operating rules — it must be fully
self-contained.

**Must:**

- Include the standard run header.
- Compose inline: global operating rules + intent-level overrides (if any) +
  run-specific constraints.
- Clearly state any run-specific constraints.

**Conflict rule:** If global rules conflict with intent-level overrides, the
override wins. The conflicting global rule must not appear in the final composite.

**Must Not:**

- Restate product intent.
- List tasks.
- Include implementation details.

**Read by:** Developer

---

### 2. `tasks.md`

**Purpose:** The exact work to be performed by the Developer.

**Must:**

- Include the standard run header.
- Contain ordered, atomic, verifiable tasks.
- Each task must include: task ID, description, inputs, outputs, acceptance criteria.
- Contain everything needed to execute without human clarification.

**Must Not:**

- Contain behavioral rules (those go in `operating-instructions.md`).
- Contain speculative or future work.

**Read by:** Developer

---

### 3. `dev-prompt.md`

**Purpose:** The execution contract for the Developer. Defines what to read,
what to do, and what to produce.

**Must:**

- Include the standard run header.
- Explicitly list every file the Developer must read.
- Bind the Developer to the run scope as defined.
- Define required outputs.
- Define how ambiguity must be handled: choose the simplest interpretation
  consistent with intent, document the decision in `results.md`, stop and report
  if blocked.

**Must Not:**

- Introduce new scope.
- Re-describe product intent.
- List `intent.md`, `trail.md`, `global-operating-instructions.md`, or any
  other intent-level or meta-level file as Developer inputs. The Manager has
  already distilled what the Developer needs into the run artifacts.

**Read by:** Developer

---

### 4. `start-dev-prompt.md`

**Purpose:** The human-run entry point for invoking the Developer. This is the
exact prompt the human copies into the Developer agent to begin execution.

**Must:**

- Reference exactly one run's `dev-prompt.md`.
- Contain no policy, scope, or behavioral rules.
- Be the last artifact created in the run bundle.

**Output requirement:** When the run bundle is complete, display the full contents
of `start-dev-prompt.md` to the user along with a request to review the bundle
before invoking the Developer.

**Read by:** Human only (copy/paste into Developer agent)

---

### 5. `results.md`

**Purpose:** The Developer's output record. Pre-created by the Manager as an
empty scaffold for the Developer to populate during execution.

**Must:**

- Include the standard run header.
- Contain empty sections: Tasks Completed, Files Changed/Added, Deviations
  from Plan, Assumptions Made, Open Questions/Blockers.

**Read by:** Developer (populates), Reviewer (evaluates)

---

### 6. `workplan.md` (optional)

**Purpose:** Manager's planning artifact for complex runs. Not read by the Developer.

**Use when:** 10+ tasks, multi-day execution, or significant coordination required.
**Skip when:** fewer than 5 tasks or the run is straightforward.

**Must contain:** intent summary, assumptions, task overview, risks and unknowns,
validation strategy.

**Read by:** Human reviewer only

---

## Scope and Authority

- Derive scope strictly from `intent.md`. Do not invent features, platforms, or services.
- No artifact outside the run contract may change scope or override constraints.
- The Developer must not access files outside:
  - The run folder (`operating-instructions.md`, `tasks.md`, `dev-prompt.md`, `results.md`)
  - `trail/intents/intent-001/files/` and subfolders (input assets only, when explicitly listed in run artifacts)
  - `trail/meta/files/` and subfolders (input assets only, when explicitly listed in run artifacts)
  - Previously produced deliverables in `Business Plan/` when explicitly referenced in run artifacts as cross-document dependencies
- The Developer must **never** read: `intent.md`, `trail.md`, `global-operating-instructions.md`,
  `operating-instructions-override.md`, `manager-instructions.md`, or any other policy/scope file
  in `trail/intents/` or `trail/meta/`. These are Manager inputs, not Developer inputs.

### Implementation Freedom

- The Developer may create additional files or helper artifacts as needed.
- Additional artifacts are non-authoritative unless explicitly referenced by the run contract.
- The Developer must not modify run contract files unless explicitly tasked.

---

## Quality Bar

- Tasks must be atomic and independently verifiable.
- `dev-prompt.md` must list explicit inputs, outputs, and validation steps.
- No scope beyond `intent.md`.
- All ambiguity surfaces in `results.md`, never silently resolved.

---

## Output Requirements

When the run bundle is complete:

1. Output: "Please review the run bundle before invoking the Developer."
2. List paths to all files created in this run.
3. Display the full contents of `start-dev-prompt.md`.