Skip to content
Skills Library
Management & product · Writing

charter

/charter

Turn a rough request into a well-formed, fleet-ready GitHub issue — then arm it. charter drafts a structured issue (imperative title, problem/goal, concrete testable acceptance criteria, scope, dependencies, notes) following issue best practices and this repo's house style, confirms the draft with you, creates it via gh with the right type label, and — by default — adds the triggerLabel from .armada/config.json so crows-nest picks it up with no extra step. Trigger when the user says "create an issue", "file a PBI", "charter a task", "new backlog item", "raise a ticket", "draft an issue", "open

Repository
armada ↗
Licence
MIT
Last repository change
05.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Turn a rough request into a well-formed, fleet-ready GitHub issue — then arm it. charter drafts a structured issue (imperative title, problem/goal, concrete testable acceptance criteria, scope, dependencies, notes) following issue best practices and this repo's house style, confirms the draft with you, creates it via gh with the right type label, and — by default — adds the triggerLabel from .armada/config.json so crows-nest picks it up with no extra step. Trigger when the user says "create an issue", "file a PBI", "charter a task", "new backlog item", "raise a ticket", "draft an issue", "open

Triggers from the description

create an issuefile a PBIcharter a tasknew backlog itemraise a ticketdraft an issue

Arguments

/charter <rough request>
Original author description

Turn a rough request into a well-formed, fleet-ready GitHub issue — then arm it. charter drafts a structured issue (imperative title, problem/goal, concrete testable acceptance criteria, scope, dependencies, notes) following issue best practices and this repo's house style, confirms the draft with you, creates it via gh with the right type label, and — by default — adds the triggerLabel from .armada/config.json so crows-nest picks it up with no extra step. Trigger when the user says "create an issue", "file a PBI", "charter a task", "new backlog item", "raise a ticket", "draft an issue", "open

How it works

  1. 0. Discover the project's conventions
  2. 1. Take the request and de-dupe first
  3. 2. Check it's one focused capability
  4. 3. Check it's buildable — push back if it's too thin
  5. 4. Draft the structured issue
  6. 5. Confirm the draft before creating
  7. 6. Modes: arm (default), no-arm, draft-only
  8. 7. Create and arm
  9. 8. Report
  10. 9. Self-improvement mode — file a fleet defect (the recursive loop)
Original SKILL.md headings · 283 lines, 2,137 words
SKILL.md preview
---
name: charter
description: >
  Turn a rough request into a well-formed, fleet-ready GitHub issue — then arm it. charter drafts a
  structured issue (imperative title, problem/goal, concrete testable acceptance criteria, scope,
  dependencies, notes) following issue best practices and this repo's house style, confirms the
  draft with you, creates it via gh with the right type label, and — by default — adds the
  triggerLabel from .armada/config.json so crows-nest picks it up with no extra step. Trigger when
  the user says "create an issue", "file a PBI", "charter a task", "new backlog item", "raise a
  ticket", "draft an issue", "open a work order", or invokes /charter. Distinct from commission
  (which sets the repo up); charter authors and arms the work that flows into the fleet.
argument-hint: "<rough request>"
disallowed-tools: Write, Edit
---

# charter — draft a fleet-ready issue and arm it

`charter` is how a rough request becomes work the fleet can build. It writes a **well-formed GitHub
issue** — the kind a human reviewer or `shipwright` can pick up without guessing — and then **arms
it** by adding the trigger label, so `crows-nest` consumes it automatically. It closes the loop on
the front end: `charter` produces the armed issues, `crows-nest` watches for them, `shipwright`
builds them.

It automates exactly what the fleet has been doing by hand: write a structured PBI, then
`gh issue edit <n> --add-label armada`. Because arming is automatic, **the quality bar matters more,
not less** — an armed issue gets built. So `charter` is opinionated about what counts as buildable
before it will create and arm anything.

> The acceptance criteria `charter` writes are the contract `shipwright` builds against and `muster`
> reviews. Vague ACs produce a vague PR. Treat them as the most important part of the issue.

## 0. Discover the project's conventions

Read `.armada/config.json` → `triggerLabel` (default `armada`) — that's the label that arms an
issue. If the file is absent the repo isn't commissioned: run
[`commission`](../commission/SKILL.md) first (or offer to), since arming keys off labels that
commissioning creates.

Two more keys matter for **self-improvement mode** (§9), where a skill files a defect against ARMADA
itself rather than authoring user work:

- `armadaRepo` — the ARMADA home repository (`owner/repo`) a self-raised fix is filed against. If
  absent, derive it from the plugin source (the marketplace/`homepage` it was installed from). A
  skill running in someone else's project must file the fix against **ARMADA**, never the host repo.
- `autoArmSelfFixes` — whether self-raised defect issues are armed. **Default `false`**: they are
  filed and labelled `fleet-defect` but left for human triage, because arming them lets the fleet
  rewrite (and, with `autoMerge`, merge) its own skills unattended. See §9.

Skim a couple of recent issues to match the house style for titles and body structure:

```bash
gh issue list --state all --limit 10
gh issue view <a-recent-number>          # see how titles/sections are written here
gh label list                            # the type labels available (enhancement/bug/…)
```

## 1. Take the request and de-dupe first

The input is a free-text description of the desired work. **Before drafting, search existing open
issues** so `charter` doesn't file a near-duplicate:

```bash
gh issue list --state open --search "<keywords from the request>"
gh issue list --state open --limit 50    # also eyeball the backlog for overlap
```

If you find a close match, surface it and ask whether to (a) build on / amend the existing issue,
(b) file anyway as distinct, or (c) drop it. Don't silently create a twin.

## 2. Check it's one focused capability

**One issue = one focused capability.** If the request is really an epic — it spans multiple
distinct surfaces, or its acceptance criteria fall into clearly separable groups — say so and offer
to file a **stack of linked issues** instead of one sprawling ticket (a foundation issue plus
siblings that reference it). A focused issue is faster to build, review, and revert; an epic stalls
the whole fleet behind one blocker. Get the user's call on splitting before drafting.

## 3. Check it's buildable — push back if it's too thin

Because `charter` **auto-arms by default**, a created issue goes straight into the build queue. So
before drafting, judge whether the request is concrete enough to produce **testable acceptance
criteria**. If it isn't — "make the dashboard better", "add some tests", "improve performance" —
**push back and get specifics first**:

- What's the observable, checkable outcome? (What would prove it's done?)
- What's in scope vs explicitly out?
- Any constraints, target files/areas, or dependencies?

Do not draft-and-arm an unbuildable issue and hope `shipwright` figures it out. Getting AC
specifics up front is cheaper than a wrong PR. (Draft-only mode — §6 — is the escape hatch when the
user just wants a body to hand-edit, not a build.)

## 4. Draft the structured issue

Write the issue following best practices and this repo's existing style. Use a concise, imperative
title of the form **`ship: capability`** (e.g. `charter: draft a fleet-ready issue and arm it`),
and a body with these sections:

```markdown
## Problem / Goal
<Why this is needed and what "good" looks like — 1–3 sentences.>

## Acceptance criteria
- [ ] <Concrete, testable outcome 1>
- [ ] <Concrete, testable outcome 2>
- [ ] <…each one independently checkable; this is the build contract>

## Scope / non-goals
- In: <what this issue covers>
- Out: <what it explicitly does not — keeps the PR focused>

## Dependencies
- <Other issues/PRs/branches this needs, or "none">

## Notes
- <Context, links, prior art, related issues.>
```

**Acceptance criteria must be concrete and testable** — each a checkbox a reviewer can tick by
observing the result, not a vague aspiration. If you can't phrase a criterion as something
checkable, that's a signal to go back to §3 for specifics.

## 5. Confirm the draft before creating

Filing a public issue is outward-facing, so **always show the full draft and confirm before
creating** — title, every section, the type label you'll apply, and whether it will be armed:

```
## Draft issue
**Title:** <ship: capability>
**Type label:** <enhancement | bug | documentation | …>
**Will arm:** yes (adds `<triggerLabel>`)  |  no (--no-arm: backlog only)  |  draft-only (won't create)

<full body as above>

Create it?
```

Adjust on feedback. Don't create until the user confirms.

## 6. Modes: arm (default), no-arm, draft-only

**Auto-arm is the default — opt-out, not opt-in.** This mirrors the single-gate model: ARMADA-
created work is armed automatically, and the real safety gate lives on the merge step
(`autoMerge`), not on manual arming. Three modes:

- **arm (default)** — create the issue *and* add the `triggerLabel`, so `crows-nest` picks it up
  with no extra step.
- **`--no-arm` / "leave it in the backlog"** — create the issue with its type label but **without**
  the trigger label, so it sits in the backlog until a human arms it.
- **draft-only** ("just show me the body", "don't create it") — print the drafted body and **do not
  call `gh issue create` at all**. Nothing is filed or armed.

If the request failed the buildable bar in §3 and the user hasn't supplied specifics, refuse to
auto-arm — offer draft-only or no-arm instead, never a created-and-armed unbuildable issue.

## 7. Create and arm

Create via `gh` with the appropriate **type label** per repo conventions (`enhancement` for a
feature, `bug` for a defect, etc.). Then, unless overridden, add the `triggerLabel` read from config
**in the same step** so there's no window where the issue exists unarmed:

```bash
# Create with the type label:
gh issue create --title "<ship: capability>" --label "<enhancement|bug|…>" --body "$(cat <<'EOF'
<the confirmed body>
EOF
)"

# Arm it (default) — add the trigger label read from .armada/config.json (default "armada"):
gh issue edit <new-number> --add-label "<triggerLabel>"
```

For `--no-arm`, skip the second command. For draft-only, run neither.

## 8. Report

Print the created issue's number and URL, its labels (type + whether armed), and what happens next:

```
⚓ Chartered issue #<n>: <title>
  type label : <enhancement|bug|…>
  armed      : yes (`<triggerLabel>`) — crows-nest will pick it up   |   no (backlog)
  url        : <issue url>
```

If armed, note that `crows-nest` will claim it on its next tick (no further action needed). If
no-arm, give the one-liner to arm it later: `gh issue edit <n> --add-label <triggerLabel>`.

## 9. Self-improvement mode — file a fleet defect (the recursive loop)

This is the **canonical convention for the whole fleet**: when *any* ARMADA skill hits a defect in
ARMADA *itself*, it routes a fix through `charter` so the fleet improves itself. The other skills
don't re-describe it — they point here. It generalises shipwright's "suggest skill improvements"
reflex (§10) into an automatic, fleet-wide one. It is the literal *Recursive* in ARMADA: the fleet
learning from its own runs.

> **Triage the failure** → if it's an **ARMADA defect**, `charter` a concise defect report **against
> the ARMADA repo**, **de-duped**, labelled **`fleet-defect`**, and **left unarmed by default** →
> note it in the run summary. Best-effort and side-channel — it **never blocks the primary task**.

### 9a. Triage first — is this ARMADA's fault, or the task's?

Only ARMADA's *own* defects get filed here. Distinguish, and when unsure default to **not** filing —
a false defect issue is noise:

- **Target-project / task problem** — the code under work is broken, a test legitimately fails, the
  issue's requirements are wrong. → Handle it normally in the build/review. **Do not** raise an
  ARMADA issue; that would pollute the fleet's tracker with the host project's bugs.
- **ARMADA defect** — a skill's instructions were wrong or missing, a guard didn't fire, the skill
  had to **guess** because guidance was absent, or the same friction keeps recurring across runs. →
  This is what self-improvement mode is for.

### 9b. Target the ARMADA repo — never the host project

File against `armadaRepo` from `.armada/config.json`, or derive it from the plugin source if that
key is absent (§0). A skill running inside someone else's repository **must** file the fix against
ARMADA's home repo with `gh issue create --repo <armadaRepo>`, so a host project's tracker is never
polluted with ARMADA's own defects.

### 9c. De-dupe against open `fleet-defect` issues

Before filing, search the ARMADA repo's open defects so the same gap isn't filed twice:

```bash
gh issue list --repo <armadaRepo> --state open --label "fleet-defect" --search "<keywords>"
```

If the defect is already filed, **add a comment or a 👍 reaction** to the existing issue (another
occurrence is signal it matters) rather than opening a duplicate.

### 9d. Draft the defect report

Use the §4 best-practice body, framed as a defect: what the skill was doing, **what went wrong**,
**why it's an ARMADA (not project) problem**, and a **suggested fix**, with concrete testable
acceptance criteria. Title it `<skill>: <the defect>` (e.g. `shipwright: base-branch guard didn't
fire on a feature-only file`).

### 9e. File it — labelled `fleet-defect`, unarmed by default (recursion risk)

Self-raised fixes modify ARMADA's *own* skills. With auto-arming + `autoMerge` on, that becomes a
**self-modifying loop that could rewrite and merge its own skills unattended** — the dream and the
hazard. Default to the safe side:

```bash
# Filed and labelled, but NOT armed — left for human triage (default):
gh issue create --repo <armadaRepo> --label "fleet-defect" --title "<skill>: <defect>" --body "<report>"
```

- Self-raised issues are labelled **`fleet-defect`** and are **not** auto-armed — even though
  `charter` auto-arms human-authored issues (§6). They sit for human triage.
- Only when **`autoArmSelfFixes: true`** in config does `charter` also add the `triggerLabel`,
  opting into the fleet fixing itself end-to-end. Leave it `false` unless the operator has chosen
  full autonomy knowingly.

### 9f. Never derail the primary task

Raising the issue is **best-effort and side-channel**. If the `gh` call fails or the repo can't be
resolved, **note it and carry on** — never block, fail, or retry-loop the build/review on a
self-improvement filing. Surface what was filed (or that filing was skipped) in the run summary
only:

```
🛠 fleet-defect filed: ARMADA#<n> "<skill>: <defect>" (fleet-defect, unarmed — human triage)
   — or — 🛠 fleet-defect: deduped onto existing ARMADA#<n>
   — or — 🛠 fleet-defect: skipped (filing failed: <reason>); primary task unaffected
```

## Best-practice guardrails (summary)

- **One issue = one focused capability** — offer a linked stack for epics (§2).
- **Acceptance criteria must be concrete and testable** — they're the build contract (§4).
- **Quality bar before auto-arming** — refuse to arm an unbuildable issue; get AC specifics first
  (§3).
- **De-dupe first** — search open issues so you don't file a twin (§1).
- **Opt-out, not opt-in** — auto-arm is default; support `--no-arm` and draft-only (§6).
- **Confirm before creating** — filing is outward-facing (§5).
- **Self-raised fixes are unarmed by default** — `fleet-defect` issues go to the ARMADA repo for
  human triage unless `autoArmSelfFixes` is on; the recursion risk is deliberate (§9).

## Inputs

- A free-text description of the desired work.
- Optional: `--no-arm` (create into the backlog, don't add the trigger label) or a draft-only
  request (show the body, don't create).
- A **fleet-defect report** from another skill (self-improvement mode, §9) — filed against the
  ARMADA repo, labelled `fleet-defect`, unarmed unless `autoArmSelfFixes` is true.

## Output

- **arm (default):** a well-formed GitHub issue, created with a type label and the `triggerLabel`,
  ready for `crows-nest` to pick up.
- **`--no-arm`:** the same issue created with its type label only, sitting in the backlog.
- **draft-only:** the drafted issue body printed, nothing created or armed.
- **self-improvement (§9):** a de-duped `fleet-defect` issue filed against the ARMADA repo (unarmed
  unless `autoArmSelfFixes`), surfaced in the run summary — never blocking the primary task.

Versions

RepositoryScoreLicence
This page · calumjs/armada100MIT
otto-haus/otto95MIT

Database snapshot: 13.11.2026 · package version 3d02b884e6b6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100agent-task
    Use when writing or drafting a GitHub issue that an AI coding agent will carry out - an issue finished in one session and one pull request, with the sections Context, Scope, Out of scope, Acceptance criteria, Tests, Depends on and Model, and the model chosen by the rules here.
  • 90issue-plan-slicer
    Convert a spec, roadmap item, or rough plan into independently implementable issue slices with scope, dependencies, acceptance criteria, and validation. Use when the user asks to split work into GitHub issues, local markdown tasks, or agent-ready implementation chunks.
  • 90issue
    Create a GitHub issue, or update an existing issue's description, with a body that captures the problem and why it matters, in the chalk voice. Use when the user says "open an issue", "file a bug", "raise an issue", "create an issue", "file a ticket", "write up a feature…
  • 85project-charter
    Turns a project brief, intake summary, or rough idea into a complete, sponsor-ready project charter. Use whenever someone says "write the charter", "start a new project", "formalise this project", "we need a charter", "draft the project document", or pastes a brief and needs it…
  • 95commission
    Commission the ARMADA fleet in the current repository — the one-time (idempotent) setup that every other ARMADA skill depends on. Detects the project's build/test/lint/run commands and base branch, writes .armada/config.json, creates the GitHub trigger + state labels, checks gh…
  • 95file-issue
    Turn a request or a discovered bug into a GitHub issue in this repo's format - interview the person until the intent is well defined, check for duplicates, then file. Use when asked to file, open, create or write up an issue, when someone describes a feature they want, or when…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.