trail.venturanomadica.com

# manager-instructions.md
<!-- This file is part of the intent package. It is read by the Manager to
     understand how to operate for this specific intent.

     This is the Manager's operational contract. It defines what artifacts
     must be created, how runs are structured, and what quality bar must be met.

     The Manager reads this file first, before reading intent.md. -->

Owner: James
Last Updated: 2026-03-14

---

## Role
<!-- Do not modify this section. It applies to every intent. -->

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/baseline.md`
3. `trail/meta/global-operating-instructions.md`
4. `trail/intents/intent-001/intent.md`
5. `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`, `baseline.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)

This intent involves building a complete website from scratch, including repository
setup, multiple pages, a PHP renderer, and deployment connection. The Manager should
expect to use `workplan.md` and should plan for more than one run if the scope
warrants decomposition.

---

## 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)
- 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.
- The Developer must **never** write to or modify the `../trail-framework/` repository.
  It is a read-only external dependency.

### 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`.