maya-project

Project management hub for the Maya dates project (ADR 0010): all issues, decisions, product docs, plans, research — and the project’s Claude Code skills, served from this repo as a plugin marketplace.

Install the skills

/plugin marketplace add drewsonne/maya-project
/plugin install maya@maya-project

Skills are then invocable anywhere, namespaced: /maya:maya-orient, /maya:maya-plan, and so on. See plugins/maya/skills/README.md for what each does and how they chain. Skills change only via a commit here plus a version bump in plugins/maya/.claude-plugin/plugin.json.

The artifacts, and how work flows between them

Seven kinds of artifact. Four live as files in this repo, three as issues.

Every skill acts at exactly one place in this flow — skills are the verbs, artifacts are the nouns. maya-orient is the exception: it reads everything and writes nothing (run it at session start).

flowchart TD
    SPEC([maya-specinterviews the Maintainer— gate G1]) --> P[Product PRDdocs/product]
    REC([maya-record]) --> R[Researchdocs/research]
    REC --> A[ADRdocs/decisions]
    R -->|"finding first, then adecision that cites it"| A
    P -->|each outcome| E[Epic]
    E --> ST[Storyunbounded backlog]
    ST -->|"gate G2: Maintainer appliesthe authorized label"| PLAN([maya-plandecomposes, justifiedby PRD + ADRs])
    A --> PLAN
    PLAN --> PL[Plandocs/plan]
    PL -->|"wave in flight + 1 only"| T[Task]
    R -->|sourced vectors| FIX([maya-fixturesbuilds the correctness suitein maya-date-fixtures])
    FIX -->|"suite must exist and pass —gates arithmetic planningand every dispatch"| FLEET
    T --> FLEET([maya-fleetpreflight, dispatch one wave,each agent undermaya-implement rules])
    FLEET --> PR[Draft pull requeston a satellite repo]
    PR --> REV([maya-reviewmechanical checks,then judgement])
    REV -->|"clean: auto-merge (ADR 0017);findings: queue for the Maintainer;Closes drewsonne/maya-project#N"| DONE[Task closedstory rolls upepic closes at gate G1]
    DONE -.->|"release PR / deploy —gate G3, the Maintainer"| SHIP[Shippedpending story #16 ADR]
    ST -.->|"outgrows one outcome:relabelled epic in place,parts become new stories"| E
    REV -.->|"silent decision or fixturedisagreement → maya-record"| REC
    FLEET -.->|"blocked, ambiguous,or plan proved wrong"| PLAN

Rounded nodes are skills; rectangles are artifacts. Not shown: maya-orient (reads all of it), and maya-implement, which is not a step but the rulebook every dispatched agent — and every hand-made change — works under between dispatch and PR.

Movement rules

• Research → ADR. When the literature says X and we therefore do Y, the finding is written first and the decision cites it — never merged into one document (maya-record).
• Product → Epic. Epics trace to PRD outcomes. A feature idea with no PRD outcome behind it prompts a maya-spec round, not a stealth epic.
• Epic → Story. Stories are created freely, at any time, for any future work (ADR 0011). Capturing an idea costs one issue; nothing worth doing lives only in a conversation.
• Story → Epic (promotion). A story that needs more than one coherent outcome is relabelled epic on the same issue; its parts become new stories beneath it. Demotion is the same move in reverse. Epics are earned from evidence of complexity, never guessed up front.
• Story → Plan → Task. When a story enters the active slice, maya-plan decomposes it into packages, each justified by the PRD or an ADR. Tasks exist for the wave in flight plus at most one planned ahead (ADR 0009); a queued wave is re-validated against main before dispatch. Decomposition is cheap to regenerate — a task inventory is a liability.
• Task → PR → closed. One task, one branch, one draft PR on the repo that owns the code, closing its task with the full cross-repo form (Closes drewsonne/maya-project#N). maya-review gates the merge; the Maintainer merges.
• Task → PR: interfaces land first. If package B needs a signature package A introduces, A lands it (a stub is enough) in an earlier wave. Two agents never negotiate an interface between themselves — they will produce two incompatible ones and both will pass their own tests.
• Story → closed. A story closes only when every task beneath it is closed and its acceptance is demonstrated against main, stated in a closing comment (ADR 0013). An epic closes when the Maintainer restates its PRD outcome as achieved.
• Anything → Research/ADR (findings loop). A fixture disagreement, a silent decision discovered in review, or a blocked package is a finding. It flows back through maya-record — the fixture is never edited to resolve it, and a planning error is fixed in the plan, not negotiated with the implementation.

The Maintainer and the three guard gates

The pipeline runs autonomously except at three human guard gates (ADR 0017), all held by the Maintainer (ADR 0015). A gate sits where a mistake is irreversible, externally visible, or a value judgment — never where correctness is mechanically checkable.

• G1 — Decide. Spec rounds (maya-spec never invents requirements), ADR acceptance, epic closure.
• G2 — Authorize. Autonomous work happens only on a story carrying the authorized label. The label covers planning and dispatching all of that story’s waves, one at a time, until done or blocked; removing it revokes the authorization.
• G3 — Ship. Release-PR merges, deploys and plugin releases are the Maintainer’s until the release ADR (story #16) says otherwise.

Between the gates, agents dispatch waves, merge clean PRs (verdict merge, zero findings, full suite green, scope clean, no fixture edits), close stories with demonstration comments, commit wave reports, and merge Dependabot PRs when the target’s full suite passes. Anything weaker queues for the Maintainer with the evidence attached — escalation is always to them, never around them. No scheduled or background execution: autonomy runs in sessions the Maintainer kicks off (“continue authorized work”).

State management: the board

The “Maya Dates” project board (project 2, linked to this repo) mirrors pipeline state (ADRs 0018/0019) — it is how the Maintainer watches autonomous work move without reading transcripts. Every hub issue and every open satellite PR is on it, with Wave/Size/Kind fields mirrored from issue metadata; transitions are performed by the skill or agent that causes the state change, via scripts/board-status.sh [owner/repo]: Backlog (filed) → Ready (authorized wave, preflight passed) → In progress (dispatched) → In review (draft PR open) → Done (closed). The board never commands — humans command via labels, issues and sessions; maya-orient reconciles the board against reality at every session start. A missing transition is a defect.

Adversarial verification

Five adversarial stages run inside the pipeline (ADR 0020), each attacking the artifact its stage produces: plan red-team before issues are filed, a bad-faith pass on every PR, a citation audit on attested vectors (three-refuter panel for calendar arithmetic), a gap analysis at wave collect, and a devil’s advocate on every ADR draft. Author ≠ reviewer is structural — review always reads the diff cold. Findings are advisory: they attach and inform, they never block a clean merge.

Measuring the process

Every dispatched wave leaves a committed report in docs/waves/ (ADR 0012): packages, fixture results, criteria met, review verdicts, findings count. Tuning the pipeline — the task horizon, package sizing, skill wording — cites wave reports, not memory. The plugin itself is CI’d: .github/workflows/validate.yml checks the marketplace and plugin manifests, every skill’s frontmatter, and that skill changes ship with a version bump.

Layout

• STATE.md — where things stand; start here.
• docs/decisions/ — numbered ADRs. 0009: the issue model. 0010: this repo. 0011: stories as the unbounded backlog.
• docs/product/ — the PRD and non-goals.
• docs/plan/ — dependency-ordered work-package waves.
• docs/research/ — sourced findings.
• plugins/maya/skills/ — the eight skills (the maya plugin).

The repos

• maya-date-fixtures — citation-backed correctness vectors (the dataset).
• maya-dates — the conversion library.
• maya-calculator-parser — date-expression parser.
• maya-calculator — the app.