Metadata-Version: 2.4
Name: planwright
Version: 0.3.0
Summary: A maker of plans: turn a Markdown plan into what's ready, what runs in parallel, and the critical path. Plain data, zero dependencies, pluggable into any project or agent.
Author: LRNSdigital
License-Expression: MIT
Project-URL: Repository, https://github.com/souzalrns/network-agents-setup/tree/main/oss/planwright
Project-URL: Issues, https://github.com/souzalrns/network-agents-setup/issues
Keywords: project-management,planning,wbs,critical-path,dependencies,scheduling,claude-code,plugin,agents,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# planwright

**A maker of plans.** Keep your plan as a plain Markdown table; planwright tells
you the three things a project manager actually needs to know:

- **what is ready to start now,**
- **what can run in parallel,**
- **what the critical path is** (the floor on how long the remaining work can take).

The plan is **data** — a Markdown file in git. The engine is **deterministic**
and has **zero runtime dependencies**. And a **Claude Code hook** keeps the plan
honest: it refuses to let the plan drift into a cycle or a dangling dependency.

Use it as a Python CLI, as a library, or as a Claude Code plugin (slash
commands + a planning skill + the hook). It is built to plug into any project or
agent and get out of the way.

---

## Why it exists

Most "project-manager" agents are a prompt persona: they write a nice plan and
then forget everything — no source of truth, no enforcement, so the work drifts
back into a pile. planwright inverts that. The plan lives in a file you own, the
schedule is computed from facts (not guessed by a model), and the discipline is
enforced by a hook rather than good intentions. See [POSITIONING.md](POSITIONING.md).

## Install

```bash
pip install planwright          # the CLI + library
```

Or use it straight from a checkout with no install:

```bash
PYTHONPATH=src python3 -m planwright.cli graph PLAN.md
```

## The plan file

A plain GitHub-flavoured Markdown table. `ID` and `Title` are the only required
columns; the rest are optional. Headers are case-insensitive and accept aliases
(including Portuguese), so planwright reads a plan written in your own words.

```markdown
| ID | Title                      | Status | Owner | Est  | Depends | Track |
|----|----------------------------|--------|-------|------|---------|-------|
| A1 | Design the data model      | done   | ana   | 1d   | -       | core  |
| A2 | Build the parser           | doing  | ana   | 2d   | A1      | core  |
| A3 | Build the dependency graph | todo   | luis  | 2d   | A1      | core  |
| A4 | Wire the CLI               | todo   | ana   | 1d   | A2, A3  | core  |
| B1 | Write the README           | todo   | bea   | 0.5d | -       | docs  |
```

- **Status**: `todo · doing · blocked · done` (aliases: `open`/`aberto`, `wip`/`em curso`, `bloqueado`, `fechado`, …).
- **Est**: a size `S/M/L/XL`, or a duration `2h` / `3d` / `1w`; `-` = not sized yet.
- **Depends**: ids this item waits on (comma/space separated); `-` = none.
- **Track**: any label to group items (a feature, a workstream, a phase).

The table can live inside a larger document — planwright reads the first table
that has `ID` and `Title` and ignores everything else.

## Commands

```bash
planwright graph    PLAN.md          # ready now · parallel layers · blocked · critical path
planwright action   PLAN.md          # a manager's action plan: ranked ready, who-unblocks-what, critical
planwright mermaid  PLAN.md          # Mermaid diagrams (deps + Kanban board) — render in GitHub/Markdown
planwright next     PLAN.md          # just the ids ready to start now (one per line)
planwright export   PLAN.md          # emit the stable JSON contract for an execution runner
planwright validate PLAN.md [--strict]  # check the plan is sound (and disciplined)
planwright status   PLAN.md          # one-line status counts
```

`graph`/`next`/`status` take `--json`; `mermaid` takes `--view deps|board|all`.
The path defaults to `PLAN.md` (override with `$PLANWRIGHT_PLAN`).

### See it, don't read it

`planwright mermaid` emits ```mermaid``` blocks that render natively on GitHub,
so a manager sees the dependency graph (coloured by status) and a Kanban board
without reading the CLI. `planwright action` ranks what to start now by leverage:
human decisions that unblock others first, then the critical path, then the rest.

### Hand-off to an execution runner

`planwright export PLAN.md` emits a stable, versioned JSON contract
(`planwright-plan/v1`) — the clean boundary between *planning* (planwright) and
*execution* (a runner). planwright describes the plan; a runner imports it,
authorizes, runs, and records. `autonomy`/`complexity` travel as **signals** for
the runner's selection logic, never as runtime policy, and planwright holds no
authz/budget/tools/events. See the monorepo's `docs/architecture/PLAN-CONTRACT.md`.

### Optional columns (for routing)

Two optional columns feed autonomy/complexity-aware routing; absent, they are
ignored:

- **Autonomy** — `auto` (an agent can close it) · `assisted` · `human` (needs a person).
- **Complexity** — `C1`..`C4` (cognitive risk, for cheap→expensive model routing),
  **independent** of `Est` (effort). A task can be `Est=S` and `C4`.

Example:

```text
$ planwright graph PLAN.md
plan: 5 items  (todo 3, doing 1, blocked 0, done 1)

READY NOW (3): start these today
  A2  Build the parser  (2d @ana)
  A3  Build the dependency graph  (2d @luis)
  B1  Write the README  (4h @bea)

PARALLEL LAYERS (2): each layer can run at once
  L0: A2, A3, B1
  L1: A4

CRITICAL PATH: 4d — A1 -> A2 -> A4
  (the floor on remaining time; shortening the plan means shortening this)
```

## As a Claude Code plugin

planwright is also a plugin. Load it straight from a checkout:

```bash
claude --plugin-dir oss/planwright          # from the monorepo root
# or, once published as its own repo / marketplace:
# /plugin install planwright --marketplace <owner>/<repo>
```

You then get:

- **`/planwright:plan-status`** — the schedule, summarised.
- **`/planwright:plan-new`** — start a plan or add an item through the method.
- **`/planwright:plan-triage`** — sort a crowded backlog into real vs. resolvable vs. stale.
- the **`governed-planning` skill** — the five-gate method (idea → research →
  spec → WBS → execute) and the one rule (nothing starts without an estimate and
  explicit dependencies).
- a **`PostToolUse` hook** — after any edit to a plan file (`PLAN.md` or
  `*.plan.md`), it validates and **blocks on an unsound schedule** so the plan
  never silently rots. Set `PLANWRIGHT_STRICT=1` to also block on governance
  warnings.

## Validation rules

**Errors** (not a sound schedule — fix before trusting the graph): a parse
failure, a duplicate id, a dependency naming no item, a self-dependency, a
cycle.

**Warnings** (schedulable but undisciplined; `--strict` turns these into
failures): an item marked `doing`/`done` with no estimate; a `done` item that
still depends on unfinished work.

## Library

```python
from planwright.parse import parse_plan
from planwright.graph import Graph

plan = parse_plan("PLAN.md")
g = Graph(plan)
print([i.id for i in g.ready()])      # ready now
print(g.parallel_layers())            # [[...], [...]]
print(g.critical_path().hours)        # float (hours)
```

## Part of a proven composition (the accountability layer)

planwright **describes and prioritizes**; it does not execute. Paired with an
execution runner it becomes an **accountability layer** for agent work: a plan
that cannot silently rot, handed to a runner that gates, budgets and verifies.
The hand-off is a thin, versioned contract — and the whole path is proven by
tests, not asserted:

- the **contract** (`planwright export` → a runner imports it):
  monorepo `docs/architecture/PLAN-CONTRACT.md`;
- the **canonical scenario** — one run with a human gate, a budget cap and
  completion checked by evidence: `docs/architecture/CANONICAL-SCENARIO.md`;
- **where it fits vs. frameworks and persona collections**:
  `docs/initiatives/COMPETITIVE-ANALYSIS.md`.

The signals planwright exports (`Autonomy`/`Complexity`) travel as *planning
intent*, never as runtime policy — the runner stays the authority at runtime.

## License

MIT. No third-party runtime dependencies. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
