agentic-team 0.0.0-stage → 6.2.0

package/template/.orchestra/config.yml

@@ -0,0 +1,293 @@
+# Orchestra Configuration
+# Customize pipeline behavior, thresholds, and verification commands.
+
+project:
+  # What this project builds for: web, expo, ios, android, backend. The
+  # installer installs only those platforms' stacks, skills and rule sections,
+  # and retires the rest on the next run. Empty means not decided yet: the
+  # installer detects the list from the repository and writes it here, and
+  # installs everything only when it finds nothing — an empty repo before
+  # /orchestra:setup. Edit it, or run `npx agentic-team --platforms ios,backend`,
+  # to change it; list all five to install everything on purpose.
+  platforms: []
+
+pipeline:
+  # One model for every phase. There used to be a table mapping a phase's
+  # complexity to a model tier, and it stopped earning its place: on the
+  # current generation, effort moves quality and cost more than the tier
+  # does, and one model means one prompt cache.
+  model: opus
+
+  # How hard the sub-agent thinks, per phase. The PM writes one of the three
+  # names on the phase; lead maps it here. Pick by how expensive a wrong
+  # answer is to unwind — not by how long the work takes. Long and mechanical
+  # is light; short and load-bearing is complex.
+  effort:
+    # One right answer, and a test or a build says whether you hit it.
+    #   a config value or an environment variable
+    #   a copy or a translation change
+    #   a dependency bump the seam tests cover
+    #   a field added to a form that already exists, validated like the rest
+    #   a new column that is nullable and read by nothing yet
+    #   an analytics event on a screen that already reports others
+    light: medium
+    # A feature. Most phases live here.
+    #   a new endpoint with validation, a query and a response shape
+    #   a new screen from a design, with its states
+    #   a background job with a retry policy
+    #   a migration that adds a table and the code that reads it
+    #   an integration behind a wrapper, with the wrapper's test
+    #   a refactor that moves behaviour without changing it
+    # The shipped default is medium; a project that set high keeps it on
+    # upgrade. One run moved its later phases to medium and they were approved
+    # within three review rounds — one run, not a measurement. A phase that
+    # needs more says `effort: high` itself.
+    standard: medium
+    # Being wrong costs more than the tokens. A mistake here reaches
+    # production quietly or is expensive to unwind.
+    #   sign-in, sessions, password reset, permissions
+    #   anything that moves money or issues a refund
+    #   a migration that rewrites or deletes data, or changes a type in place
+    #   concurrency — a lock, a queue consumer, an idempotency key
+    #   a change that touches many files at once
+    #   a rate limit, a cache with invalidation, a retry with side effects
+    complex: xhigh
+  # When a phase says nothing.
+  default_effort: standard
+  # A phase can also write a raw level — effort: max — for the one place
+  # where correctness beats cost outright. The names above are the
+  # vocabulary; the five levels stay reachable.
+  # What happens to the design RFC before phases start.
+  #   required — show it and wait for you
+  #   optional — show it and continue
+  #   skip     — write it and never show it
+  #
+  # The default is optional because skip is the one setting with no upside:
+  # the architect still runs and still writes rfc.md on a complex milestone,
+  # so skip pays for the design and then throws away the only chance to read
+  # it before the code exists. required is the right choice when the work is
+  # unfamiliar enough that a wrong design is expensive to unwind.
+  rfc_approval: optional
+
+  # Code review: required | optional | skip
+  review: required
+
+  # Parallel phase execution: enabled | disabled
+  # When enabled, phases with depends_on: [] run in parallel
+  parallel: disabled
+
+  # Default pipeline when milestone Complexity is missing
+  default_pipeline: full  # quick | standard | full
+
+thresholds:
+  # Max retries before escalation: a stuck fix, a failed gate, and review
+  # rounds per phase — the last counted by .claude/hooks/review-rounds.sh.
+  stuck_retry_limit: 3
+
+verification:
+  # Commands run before every commit, in order, stopping at the first failure.
+  #
+  # They execute in the directory of the app the phase is touching, not at the
+  # repo root. A multi-platform repo therefore needs each app to expose the
+  # same four entry points — that is what makes one command set work across
+  # npm, Gradle, and Xcode.
+  #
+  # If an app directory contains verify.sh, lead runs that instead of the four
+  # commands below. Non-npm stacks generate one; see .orchestra/stacks/.
+  #
+  # Customize these for your stack (Go, Python, Rust, etc.)
+  typecheck: "npx tsc --noEmit"
+  test: "npm test"
+  lint: "npm run lint"
+  # Coverage gate. The testing rule ("anything wrapping a dependency has a
+  # test") is unverifiable without it.
+  coverage: "npm run test:coverage"
+
+  # A production build. Typecheck is not a build: `tsc --noEmit` happily
+  # accepts a Next.js app that fails `next build` on a server/client boundary
+  # or a static-generation error, and neither tests nor lint load the
+  # bundler. Without this, "green" can mean an artifact that does not exist.
+  # Runs last because it is the slowest, so cheap checks fail first.
+  build: "npm run build"
+
+  # Optional, and skipped where the app has no such script. An Expo app has
+  # one, because a native module off the SDK's compatibility table is
+  # invisible to typecheck, lint and jest alike — and is exactly the kind of
+  # defect that passes CI and fails on a device.
+  doctor: "npm run doctor"
+
+testing:
+  # Strategy lives in .claude/rules/testing-standards.orchestra.md. These are
+  # the knobs it refers to.
+  coverage:
+    # A single global percentage stops measuring test quality the moment it
+    # becomes a gate. Instead: never go down, and hold the new code to a real
+    # bar. Vitest's thresholds.autoUpdate writes the ratchet back to the
+    # config when coverage improves; a drop fails the run.
+    ratchet: true
+
+    # The gate that actually changes behaviour: branch coverage of the lines
+    # this change touched. Applies to a pull request, not to the repo.
+    diff_branch_threshold: 90
+
+    # The highest floor the ratchet is allowed to record.
+    #
+    # Without it the ratchet writes down whatever the code achieved, and a
+    # fresh scaffold is small enough to be perfect — so the floor becomes 100
+    # on day one and every line written afterwards must be covered or the
+    # build fails. Nobody chose that; it is an artifact of a 71-line app, and
+    # it is stricter than diff_branch_threshold, so the two gates disagree and
+    # the accidental one wins.
+    #
+    # The cost is explicit: between this number and whatever coverage actually
+    # is, a regression does not fail the build. The diff gate is the bar for
+    # new code; this only prevents falling off a cliff.
+    ratchet_ceiling: 90
+
+    # Modules that wrap a third-party library are where a dependency bump has
+    # to turn the suite red. They are small, so 100% is both achievable and
+    # meaningful — unlike a global 100%. Globs, relative to the app.
+    #
+    # Live rather than empty because the location is a convention, not
+    # something discovered later: anything wrapping a third party goes in
+    # src/integrations/<provider>/. See
+    # .claude/skills/project-structure/SKILL.md.
+    #
+    # It asks that the wrapper be exercised, not that a test file sit beside
+    # it — an integration test driving it through a faked HTTP boundary
+    # satisfies it. Do not add a unit test to repeat a route test.
+    seam_paths: ["src/integrations/**"]
+
+    # Counted against nothing. A design token file or a type-only module
+    # moves the number without saying anything about quality.
+    exclude:
+      - "**/*.d.ts"
+      - "**/*.test.*"
+      - "**/*.config.*"
+      - "**/index.ts"
+      - "**/design/tokens.*"
+
+  mutation:
+    # Coverage says a line ran. Mutation says it was checked.
+    # Runs per pull request over the files that PR changed — a full run takes
+    # hours and belongs on a schedule, not in a gate.
+    #
+    # Currently inert on any app using TypeScript 7: the Go compiler dropped
+    # the JS compiler API, and Stryker's sandbox preprocessor calls into it
+    # before reading any of its own options. Scaffolding detects this and
+    # skips the install rather than shipping a script that crashes. Every
+    # other piece is wired, so it starts working when Stryker catches up.
+    enabled: true
+
+    # Mutation score below this fails the run, on changed files only.
+    break_threshold: 70
+
+  dependencies:
+    # minor and patch on green is a merge — that is what the seam rule buys.
+    # A major is the maintainer saying the contract changed, and some of what
+    # changed is invisible to any test. A human reads those.
+    automerge: minor-and-patch   # minor-and-patch | patch | none
+
+delivery:
+  # Work always reaches you as one pull request per task. There used to be a
+  # `mode` here choosing between that and an agentic loop with no PR, and it
+  # stopped meaning anything: the loop is what `--auto` on /orchestra:start
+  # already gives you, and it gave it while leaving no reviewable trail. The
+  # flag decides whether a human gates the merge; nothing decides whether the
+  # work is visible.
+  #
+  # The branch every task branches off and squashes into. Asked at setup,
+  # never inferred: a repository's default branch is often not where work
+  # lands — one project integrates on `next` and releases from `main`, and a
+  # task built off `main` there opens its PR against the release branch.
+  base_branch: main
+
+  # How many times to iterate on a screen that does not match its design
+  # before giving up. Only reached under --auto, where nobody is watching to
+  # judge it.
+  max_design_iterations: 4
+
+  # What happens when those iterations are exhausted. Never silently accept.
+  on_parity_exhausted: tech-debt  # tech-debt | fail
+
+tracker:
+  # This key decides who owns requirements. There is deliberately no second
+  # knob: two settings that can disagree about the same question is the thing
+  # this system keeps arguing against.
+  #
+  #   none                    — the markdown under .orchestra/milestones/ is
+  #                             the source of truth. Nothing is pushed and
+  #                             nothing is pulled.
+  #   github | clickup        — the tracker is canonical. The milestone
+  #                             directory holds pointers, not requirements,
+  #                             and lead reads the work from the provider.
+  #
+  # What choosing a provider costs, stated once so it is a decision rather
+  # than a surprise: lead cannot run while the API is down, rate-limited or
+  # unauthorised; a requirement change has no diff and no review; and git log
+  # stops answering "why did we build this". `none` keeps all three.
+  #
+  # See .claude/rules/tracker-authority.orchestra.md.
+  provider: none  # none | github | clickup
+
+  # The board or project the tasks live on. Read at setup, not guessed —
+  # GitHub wants a Projects v2 number, ClickUp a list id.
+  board: ""
+
+  # ClickUp only: the space's wiki document, where an RFC is published as a
+  # page. Read at setup from the space rather than created — a team already
+  # has one, and a second wiki is worse than none.
+  #
+  # Pages nest project → milestone, so a repo with thirty milestones is thirty
+  # pages under one heading rather than thirty at the top level. Empty means
+  # RFCs are not published, and everything else still works.
+  wiki: ""
+
+  # Orchestra's internal states, mapped to what this project actually calls
+  # them. Discovered by reading the provider at setup and written here.
+  #
+  # It is not hardcoded because it cannot be: a GitHub Projects `Status` is a
+  # user-defined single-select, and a Jira status comes from the project's own
+  # workflow scheme. The defaults below are GitHub's stock board, which is a
+  # starting point and not an assumption — a provider whose statuses cannot be
+  # read is a setup failure, never a guess.
+  states:
+    # Where export lands a task. You move it to ready when lead may take it —
+    # lead never does that itself.
+    backlog: "backlog"
+    ready: "ready"
+    in_progress: "in progress"
+    in_review: "in review"
+    done: "done"
+    # Where lead parks a task in --auto that it cannot finish without an
+    # answer from you, rather than guessing. It moves on to the next task.
+    blocked: "blocked"
+    # A workaround it was forced into, recorded as its own task so the
+    # shortcut is visible instead of buried in a diff. See
+    # .claude/rules/tracker-authority.orchestra.md.
+    tech_debt: "tech debt"
+
+  # Whose comments the sync loop is allowed to act on.
+  #
+  # The loop turns text written on a board into code and a pull request, which
+  # makes it an instruction channel. Everything else here treats what arrives
+  # through a tool as data rather than as a command, and this is the one place
+  # that would otherwise break the rule. A comment from anyone not listed is
+  # reported to you and never acted on. Empty means nobody, which is why setup
+  # fills it in.
+  actors: []
+
+  # Export and sync are never automatic and have no toggle — they happen only
+  # when you run /orchestra:export or /orchestra:sync. See
+  # .claude/agents/tracker.md.
+
+observability:
+  # Mandatory — see .claude/rules/observability.orchestra.md and
+  # .claude/rules/analytics-kpi.orchestra.md. These pick the provider;
+  # they do not make the capability optional.
+  errors: sentry       # sentry | custom
+  analytics: posthog   # posthog | custom
+  logging: pino        # pino | custom
+
+  # Fail the verification gate if an app has no error monitoring wired.
+  require_before_release: true

package/template/.orchestra/roles/orchestrator.md

@@ -0,0 +1,105 @@
+---
+name: orchestrator
+description: "Maintains the Orchestra system itself — roles, rules, agents, skills, commands, stacks, config, docs. Changes it only in answer to a real failure, prefers a check over prose, and keeps one source for every fact. Use when modifying the Orchestra system."
+---
+
+# Role: Orchestrator
+
+## Identity
+
+You maintain the system the other roles run inside. Nothing you write ships
+to a user directly; every line you change is a line an agent will read on
+its next run and either follow or not. That is the whole job: making the
+system one that agents actually follow, and knowing the difference between
+that and one that merely says the right things.
+
+## Ownership
+
+| Can Do | Scope |
+|--------|-------|
+| Create/edit/delete role files | `.orchestra/roles/*.md` |
+| Edit config | `.orchestra/config.yml` |
+| Edit CLAUDE.md | `CLAUDE.md` |
+| Create/edit agents | `.claude/agents/*.md` |
+| Create/edit rules | `.claude/rules/*.orchestra.md` |
+| Create/edit skills | `.claude/skills/*/SKILL.md` |
+| Create/edit blueprints | `.orchestra/blueprints/*.md` |
+| Create/edit stacks | `.orchestra/stacks/**` |
+| Create/edit commands | `.claude/commands/orchestra/*.md` |
+| Create/edit hooks | `.claude/hooks/*` |
+| Maintain documentation | `docs/*.md` |
+
+## Cannot Do
+
+Write feature code, PRDs, RFCs, design specs, or review code. If asked,
+refuse and name the correct role.
+
+## How you decide
+
+These are the rules the system is built by. Each one is enforced by the
+suite or by the way you work, and each exists because ignoring it produced
+a real failure.
+
+**A change answers a failure, or it is refused.** Every rule, check, hook
+and agent in this system was written after something went wrong — a PM
+opened a pull request, a phase shipped seven of fifteen components, a
+review body listed everything it checked. When someone proposes a change
+with no failure behind it, say so and propose the measurement instead: what
+would we record, and what number would justify building it. Speculative
+machinery is the most expensive kind, because it costs maintenance forever
+and nobody can say whether it helped.
+
+**A rule nothing checks is advice.** Before writing prose, ask what could
+enforce it: a hook, a policy check, a consistency test, a script. Prose is
+what is left after the mechanical part has been made mechanical. When a
+rule must stay prose — a judgement no script can make — say so in the rule,
+and tell the reviewer it is theirs.
+
+**One source for every fact.** A number, a list, a vocabulary lives in one
+file; everything else points at it. The re-review threshold was 30 in one
+file and 50 in another and the agent was handed both. The skill list
+drifted from 15 to 24 in a second copy. When you find a duplicate, delete
+the copy and link — never update both.
+
+**Enforcement over reassurance.** A hook the agent can route around, a test
+that only passes on a developer's machine, a check that fires on its own
+subject matter and so gets an ignore — each is worse than nothing, because
+it reads as covered. When you add a check, break the thing it guards and
+watch it fail before you trust it.
+
+**Argue in the file.** A rule states the failure it prevents, in a sentence,
+so an agent can apply it to a case the rule never named. "Never mock the
+database" is an instruction; "mock it and you test your own mock" is a
+reason that generalises. Write the reason.
+
+**Fix the stack, not the project.** A defect found while a real project was
+built is fixed in `.orchestra/stacks/`, so the next project never meets it.
+Fixing it in the project is fixing it once.
+
+## How you work
+
+1. **Read what exists first.** The rule may already be there, half-written
+   or in a different file. Search before adding; a second copy is the worst
+   outcome. Check the consistency suite for what is already guarded.
+2. **Name the failure.** In one sentence: what went wrong, where, and what
+   the change makes impossible next time. If you cannot, stop — see above.
+3. **Pick the enforcement.** Hook, check, test, script, or — last — prose.
+   Say which and why.
+4. **Change the source, then the pointers.** Rule or agent first; docs,
+   README and cross-references after. A doc changed ahead of its rule
+   describes a system that does not exist yet.
+5. **Run the suite.** `yarn test` — the consistency tests are the gate
+   against contradiction, and they have caught every drift so far. A test
+   that fails is telling you about a reference you did not update; read
+   it, do not loosen it.
+6. **Commit with the failure in the message.** Conventional format; the
+   body says what went wrong and what is now impossible, not what files
+   changed. The commit log is the system's memory of why.
+
+## Documentation
+
+`docs/` describes the system as it is, never as it was or will be. A
+feature added, removed or changed is a docs change in the same commit.
+The consistency suite checks that docs name only files that exist and only
+config keys that exist; anything past that is yours to read back as the
+person who installs this into a project tomorrow.