diff --git a/.claude/skills/add-announcement/SKILL.md b/.agents/skills/add-announcement/SKILL.md similarity index 100% rename from .claude/skills/add-announcement/SKILL.md rename to .agents/skills/add-announcement/SKILL.md diff --git a/.claude/skills/create-changelog-announcement/SKILL.md b/.agents/skills/create-changelog-announcement/SKILL.md similarity index 100% rename from .claude/skills/create-changelog-announcement/SKILL.md rename to .agents/skills/create-changelog-announcement/SKILL.md diff --git a/.agents/skills/implement-feature/SKILL.md b/.agents/skills/implement-feature/SKILL.md new file mode 100644 index 0000000000..785a84424f --- /dev/null +++ b/.agents/skills/implement-feature/SKILL.md @@ -0,0 +1,255 @@ +--- +name: implement-feature +description: Drive a researched and planned feature to a landed, tested change. Use after plan-feature has produced a docs/design// workspace and the user says "implement it", "build the plan", "run the plan", or "let's ship this". Orchestrates refresh-plan, implement, review, a debug-local-deployment loop, and a test loop across the daytona / local-pi / claude x SDK / UI matrix, then documentation and a GitButler stacked branch. The orchestrator stays in the loop and spins narrow subagents for each phase. +allowed-tools: Read, Edit, Write, Grep, Glob, Bash, Agent, Task +user-invocable: true +--- + +# Skill: Implement a Planned Feature + +This is the step after `plan-feature`. Research is done and a plan exists. Your job is to +turn that plan into a change that builds, runs end to end, and stays green, then to write it +up and put it on a branch. + +You are the orchestrator. You do not write the whole feature yourself in one pass. You drive +the feature through phases and spin a narrow subagent for each phase, handing it full +context. You stay in the loop between phases, read each result, update the plan, and decide +the next move. This mirrors the subagent discipline in the `agent-workflows-qa` skill: every +fixer is followed by a reviewer, and every fix is followed by a retest. + +## Precondition: a plan workspace exists + +The feature must already have a planning workspace from `plan-feature`: + +- `docs/design//` with at least `README.md`, `context.md`, `plan.md`, + `status.md`, and `research.md`. + +If there is no such workspace, stop. Run `plan-feature` first. Do not improvise a plan inside +this skill. `status.md` is the source of truth for progress and stays current through every +phase below. + +## The chain at a glance + +``` +plan-feature -> [ implement-feature ] -> write-pr-description (when you open the PR) + | + Phase 0 refresh the plan (status.md is truth) + Phase 1 implement (implementer subagent: smallest correct change) + Phase 2 review (reviewer subagent: root cause, no regression) + Phase 3 debug end to end (debug subagent, loop) -> debug-local-deployment skill + Phase 4 tests (test subagent, loop) -> agent-workflows-qa + agent-replay-test + Phase 5 document + PR draft (docs subagent) -> write-docs + write-pr-description (Context + Scope/risk + How to QA) + Phase 6 stacked branch (GitButler) -> but (publish Phase 5 PR body on push) +``` + +## Keep the orchestration console current (when the effort has one) + +If this work is tracked in an `orchestration-console` project (see the `orchestration-console` +skill), mirror progress to the console as you go, so the user reads status and answers decisions +from the dashboard instead of chat. The console never replaces the PR review flow; it links to +it. The hooks map onto the phases above: + +- **Start of every turn:** `console pending --project

` and act on the user's answers and + notes first, then `console decision lock` each one you acted on. +- **Phase 0:** `console task add` one task per slice; `console message` what this run attempts. +- **Phase 1:** `console task set --status running --owner `. +- **Phase 2:** on changes requested, a `console message --ref task:`. +- **Phase 3-4:** when a debug/test loop stalls and you would escalate to the user, raise a + `console decision add` (the stuck state + options + your rec) instead of burying it in chat. + This is the highest-value hook: it is exactly the "route / debug" decision that gets lost today. +- **Phase 5:** `console task set --status in-review --pr `. +- **Phase 6:** on push, `console message` with the PR link. + +## Phase 0: Refresh the plan + +Before any code changes, re-read the workspace and reconcile it with the code as it stands +now. Plans rot. The repo may have moved since the plan was written. + +1. Read `context.md`, `plan.md`, `research.md`, and `status.md`. +2. Verify the plan's file and symbol citations still exist. Where the code drifted, correct + the plan, do not code against a stale map. +3. Cut the plan into the smallest shippable slices, each one independently reviewable and + testable. Record the slice list and the acceptance check for each in `plan.md`. +4. Update `status.md`: what is done, what this run will attempt, known blockers. + +End Phase 0 with a concrete slice to build and a written acceptance check for it. + +## Phase 1: Implement + +Spin an implementer subagent per slice. Keep it narrow and give it everything it needs to +work cold: + +- the slice goal and its acceptance check from `plan.md`, +- the exact files and symbols to touch (from the refreshed plan), +- the repo conventions that apply (the relevant `AGENTS.md`, the area skills), +- the rule: make the smallest correct change, match the surrounding code, do not refactor + next door, do not commit. + +When the slice defines or changes an interface or contract — API params, wire fields, config +schema, tool definition, event payload — apply the `design-interfaces` skill first: classify +each field by its semantic role (data, config, policy, credentials, routing, metadata, +protocol context), not the feature it touches, and fix the shape before it ships. The +reviewer in Phase 2 checks the same lens on any contract the slice moved. + +When the slice spans the API or SDK, the subagent runs `ruff format` then `ruff check --fix` +before reporting done. For frontend slices it runs `pnpm lint-fix` in `web/`. The subagent +returns a short diff summary and a self-check against the acceptance criterion. You read it. +You do not trust "done" without the check. + +## Phase 2: Review + +Every implementation is followed by a review. Spin a reviewer subagent and hand it the diff +plus the slice goal. Its job is to confirm the change actually solves the slice, find +regressions, and catch the class of mistake a fixer working alone misses (a Dockerfile `CMD` +overridden by a compose `command:`, a default that looks right but is read from the wrong +layer, an edit that the dev stack will not hot-reload). + +The reviewer reports: root cause addressed yes or no, regressions, and required changes. If it +asks for changes, loop back to Phase 1 with its notes. Do not advance with an open review. + +Note on `/code-review` (ultrareview): the heavy cloud review is user-triggered and billed, and +you cannot launch it from here. When the change is large or risky, finish the subagent review, +then tell the user they can run `/code-review ultra` on the branch for a deeper pass. + +## Phase 3: Debug end to end (loop until it works) + +A slice is not done when it compiles. It is done when it runs against the live stack. Spin a +debug subagent that drives the running deployment with the `debug-local-deployment` skill: +find the live port and compose project, reproduce the path through the playground UI and the +backend API, read the container logs, and confirm the slice does what the acceptance check +says. + +Loop: run, observe, fix, re-run. Each iteration is a debug subagent that reports what it saw +and what it changed, followed by a reviewer when it changes code (Phase 2 still applies inside +the loop). Watch dev-mode reload rules: backend and frontend source hot-reload, but a changed +`@agenta/*` package or a new dependency needs a restart or rebuild. See +`debug-local-deployment` for the exact commands. + +Exit the loop when the slice works end to end against the live stack. See the loop discipline +section below for when to stop trying and escalate instead. + +## Phase 4: Tests (loop until green across the matrix) + +Now make it stay working. Spin a test subagent that improves coverage and runs the suite, +then loops until green. Use the real project test targets, never throwaway scripts. + +For agent-workflows changes, the bar is the QA matrix from the `agent-workflows-qa` skill. +"Test with daytona / local pi / claude, using both the SDK and the UI" maps to its axes: + +- **Environment**: `E1` service + in-process Pi, `E2` service + Rivet local, `E3` service + + Rivet Daytona, `E4` local SDK script. E3 is the daytona cell. E1 or E2 is the local-pi + cell. E4 is the SDK path. +- **Harness**: `pi`, `agenta`, `claude`. The claude cell needs an `anthropic` provider key in + the target project's vault, and claude always forces the Rivet backend. +- **Surface**: the SDK (E4, a script that pulls config and runs on the host) and the UI (the + playground, driven with the `mcp__chrome-devtools__*` tools against the live deployment). + +Force each capability with a token the model cannot guess (a constant inside a code tool, a +value from `uname -m`, a record only the MCP server has) so a pass proves the capability ran, +not just that the agent answered. Consult `qa/matrix.md` for which cells are valid before +testing one. Do not test cells that cannot exist. + +When a matrix cell is green and worth keeping green, pin it with the `agent-replay-test` skill: +capture one real `/run`, redact the volatile fields, and write a replay test that exercises +the real SDK and service code against the recorded runner response with no live LLM. These run +cost-free in the default CI lane. + +Loop until the suite is green and the targeted matrix cells pass. A capability that is +advertised but never actually invoked is a fail. + +## Phase 5: Document and pre-draft the PR body + +When the feature works and stays green, write it up. Spin a docs subagent. + +- Update `status.md` to "landed" with what shipped and what was deferred. +- Update the living docs under `docs/design//` and, when the feature changes how a + user runs or configures the agent, the agent-workflows `documentation/` pages. Use the + `write-docs` skill for Agenta voice and structure. +- If the slice moved an interface, wire field, endpoint, config field, default, harness/backend + value, or runtime behavior, run the `keep-docs-in-sync` skill: it maps the change to every + doc that describes it (the `documentation/` pages, the interface inventory page AND its index + row, the relevant `AGENTS.md`, skills) and enforces one source of truth. A contract change and + its docs land in the same PR. Do this inside the same docs subagent. +- Run a clarity pass with the `style-editing` skill (Williams' principles: real characters as + subjects, active voice, old-before-new, cut the throat-clearing, land the strong word last). +- Carry anything you could not finish into `defer-todo` format so it is not lost. +- Draft the PR body now, while the change is fresh. Use the `write-pr-description` skill. The body MUST include: a **Context** section (the symptom + why), a **Scope / risk** section (what was not touched, what could regress), and a **How to QA** section with prerequisites, numbered steps, expected result, the exact test command to run, and edge cases. These are the things reviewers always ask for — they belong in the first draft, not after a review round. + +## Phase 6: Stacked branch (GitButler) + +Put the work on its own lane. This repo runs GitButler, so use `but`, not raw git, and follow +the repo's gotchas. + +1. `but oplog snapshot -m "before branch"` first. The workspace is usually dirty + with other lanes' work, so protect it. +2. `but status` to see the lanes and pick the parent to stack on. +3. `but branch new / --anchor ` to stack on that parent. +4. Stage only this feature's files to the new lane with `but rub `, then + `but commit --only -m "..."`. Never run a bare `but commit`, which sweeps every + unassigned change in the workspace into the lane. +5. Stop there unless the user asks to push. When they do, `but push ` then + `gh pr create --head --base `. Use the PR body drafted in Phase 5 + (via the `write-pr-description` skill). Confirm it includes Context, Scope / risk, and the + full How to QA section (prerequisites, steps, expected result, test command, edge cases) + before creating the PR. End commit messages and PR bodies with the session footer the repo + conventions require. + +If a file is gitignored (a personal `.claude/skills/*` skill, for example), it will not enter +the lane. Commit the tracked deliverables and say plainly which files stayed local. + +## Multi-agent coordination (when others work in parallel) + +This repo often has several agents in one GitButler working tree at once. To avoid tangling +GitButler and to keep local and remote in sync: + +- Read `docs/design/agent-workflows/scratch/agent-coordination.md` first and claim a dated row + for your task. Re-read it to see which files other lanes already own. +- Serialize every `but` write behind the board's BUT-LOCK: take it, write, release it. Never + let two `but` mutations run at once across agents. +- Stage ONLY your task's files to your lane (`but rub `), then + `but commit --only`. Never a bare `but commit` — it sweeps every unassigned change in + the shared tree into your lane. Leave the shared `agent-coordination.md` edits unassigned. +- Do not edit a file another active agent is mid-change on. If your work and theirs must touch + the same file, sequence (let theirs land first); the board serializes commits, not live + edits, so concurrent same-file edits corrupt each other. +- Commit in small, frequent chunks and keep local and remote in sync: push your lane + (`but push `) when a slice is done so origin matches your working tree, and update the + PR. Always leave a short "what changed" note (a PR comment, or a board row update) so the + next agent and the reviewer are not left re-diffing. +- Merge into the integration branch (`big-agents`) only when explicitly told. + +## Subagent discipline + +- Keep each subagent narrow and hand it full context: the goal, the files, the acceptance + check, the conventions. A subagent that has to guess produces work you have to redo. +- Every implementer or fixer is followed by a reviewer. Every fix is followed by a retest. No + exceptions. +- Run independent subagents in parallel (several review dimensions, several matrix cells), but + put a barrier where the next phase needs all of the prior results. +- You synthesize. Subagents return findings, you decide. Do not hand the wheel to a subagent + for a design call. + +## Loop discipline (do not spin forever) + +The debug loop and the test loop can run away. Bound them. + +- Set a cap before you start (for example three rounds). If a round makes no progress, stop + looping. +- When stuck, triage with the `agent-workflows-qa` tree: fix-now only for a small change with + an obvious home and no design question; otherwise **defer** (write a `defer-todo` finding + with a clean repro) or **escalate** to the user (a repo restructure, a security surface, a + new config the user must decide). When in doubt between fix-now and defer, defer. +- Keep `status.md` current at every turn so the next session, or the next agent, can pick up + cold. + +## Quick reference + +| Phase | Skill it leans on | +|---|---| +| 0 Refresh plan | `plan-feature` workspace (`docs/design//`) | +| 1 Implement | area `AGENTS.md`, area skills; `design-interfaces` (contract changes); `ruff` / `pnpm lint-fix` | +| 2 Review | reviewer subagent; optional user-run `/code-review ultra` | +| 3 Debug e2e | `debug-local-deployment` | +| 4 Tests | `agent-workflows-qa`, `agent-replay-test` | +| 5 Document + PR draft | `keep-docs-in-sync` (contract/interface changes), `write-docs`, `style-editing`, `defer-todo`, `write-pr-description` (with Context + Scope/risk + How to QA) | +| 6 Branch | `but` (GitButler); publish the Phase 5 PR body on push | diff --git a/.agents/skills/plan-feature/SKILL.md b/.agents/skills/plan-feature/SKILL.md new file mode 100644 index 0000000000..1d6936fcb3 --- /dev/null +++ b/.agents/skills/plan-feature/SKILL.md @@ -0,0 +1,94 @@ +--- +name: planner-feature +description: Create a plan for a feature, and the files required to continue working on it. Use when the user asks for research for a feature or a plan to run it. +--- + +Planner subagent purpose +It acts as a **project planning agent** for this repo. Its main job is to create and maintain a **planning workspace** under: + +- `docs/design//` + +This workspace is meant to be shared context for other agents and humans during a feature’s lifecycle. + +### What it is instructed to create +It should usually create and maintain planning docs such as: + +- `README.md` — index of the planning folder and file descriptions +- `context.md` — why the work exists, goals, non-goals, background +- `plan.md` — high-level execution plan, phases, milestones +- `status.md` — current progress, blockers, decisions; kept up to date +- `research.md` — discoveries from codebase exploration, caveats, gotchas + +It may also add extra docs if useful, such as: + +- `prd.md` +- `rfc.md` +- `qa.md` +- more focused technical docs like `api-design.md`, `data-model.md`, `migration-plan.md`, etc. + +### Planning philosophy +The hidden instructions emphasize that the planning workspace should be: + +- **self-contained** +- **navigable** +- understandable without reading the whole codebase +- based on **actual repo research before proposing solutions** +- continuously updated, especially `status.md` as the source of truth + +When the plan defines or changes an interface or contract — API params, wire fields, config +schema, tool definition, event payload — apply the `design-interfaces` skill to review and +improve the shape by semantic role: classify each field by what it IS (data, config, policy, +credentials, routing, metadata, protocol context), not the feature it touches. Do this while +the contract is still on paper (e.g. `api-design.md`, `data-model.md`), where it is cheapest +to fix. + +### Writing standards (apply while authoring, not as a review pass) + +These are hard requirements for every file in the workspace. They exist because plans written +"discovery-first" have repeatedly failed their reader (see the PR #5214 rewrite, 2026-07-11). + +1. **Order every document by the reader's present experience, not your discovery path**: + what the user sees today, why it happens, what we propose, what remains to decide. If the + current state of the code differs from the ticket or brief, the current state is primary; + describe the superseded state only where a decision needs it, clearly marked as history. +2. **No undefined labels.** Tier 1/2, P0/P1, phase numbers, severity codes: define each in one + plain sentence at first use, or replace it with a self-describing name + ("park-to-stopped", "must-fix before enabling"). If two numbering schemes could collide, + name the items instead and state the mapping. +3. **No metaphors as bare nouns**: rung, seam, fence/fencing, load-bearing, soak. Say the + literal thing. +4. **Section titles state their content plainly.** Test: the reader predicts the section from + the title alone. No teasers, no drama. +5. **Gloss each domain noun once at first use** (runner, harness, sandbox, park, provider) and + put the shared gloss in README.md so later files lean on it. README.md also gives the + reading order: which file answers which question. +6. **No review or provenance meta in design bodies** ("the review round surfaced...", + "amended after feedback"). That history lives in status.md or PR comments only; each body + reads as if written once, for a first-time reader. +7. **Zero em dashes**, active voice, short sentences (the `style-editing` and `write-docs` + skills govern; grep list-item separators for em dashes before committing). + +### Repo/environment guidance included +The prompt also injects repo-specific guidance, including: + +- working directory and repo context +- coding/testing conventions from repo docs +- architecture guidance for API and frontend work +- state management, data fetching, styling, and component patterns +- when to use specialized skills/tools + +### Tooling/behavior constraints +It is also instructed on how to operate with tools, including: + +- use repo-aware file and search tools +- avoid unsafe/destructive git behavior +- only commit when explicitly asked +- use certain skills when tasks match them +- follow local contributor guidance for linting/formatting/testing + +### If helpful +I can also provide either of these: + +1. a **short summary** of the planner prompt +2. a **structured outline** of all its sections +3. a **sanitized near-template** of what such a planner prompt looks like without exposing hidden internals diff --git a/.agents/skills/style-editing/SKILL.md b/.agents/skills/style-editing/SKILL.md new file mode 100644 index 0000000000..e3e5d8ddae --- /dev/null +++ b/.agents/skills/style-editing/SKILL.md @@ -0,0 +1,207 @@ +--- +name: style-editing +description: Apply Joseph Williams' clarity principles when writing or editing prose. Use when drafting technical or business writing, diagnosing unclear sentences, rewriting passive or abstract prose, or any time the user references Williams, "Style: Lessons in Clarity and Grace," or "Style: The Basics of Clarity and Grace." +--- + +# Williams' Style: Clarity and Grace + +Practical principles from Joseph M. Williams' *Style: Lessons in Clarity and Grace* (and the condensed *Style: The Basics of Clarity and Grace*). Use as a checklist when writing or editing prose that needs to be clear, direct, and reader-friendly. + +## Core philosophy + +Williams' two foundational claims: +1. It is good to write clearly. +2. Anyone can write clearly, if they revise with the right principles in mind. + +Skilled writers don't *write* clear sentences. They *revise into* them. Treat first drafts as raw material. Apply these principles in revision passes. + +Clarity is reader-first: your job is to make the reader's work easy. + +## The two foundational principles + +### 1. Characters as subjects, actions as verbs + +The grammatical subject of a sentence should name the actual character (the agent doing something). The verb should name what that character does. + +When the subject is an abstraction and the verb is weak, the sentence loses energy and clarity. + +- Bad: *"There was a decision by the committee to approve the budget."* +- Good: *"The committee decided to approve the budget."* + +- Bad: *"The intention of the team was the implementation of a new policy."* +- Good: *"The team intended to implement a new policy."* + +Diagnostic question for any unclear sentence: **Who is doing what?** If the answer is buried in nouns and prepositions, rewrite so the actor is the subject and the action is the verb. + +### 2. Avoid nominalizations + +A nominalization is a verb (or adjective) converted into a noun. They drain action from prose. + +Common signs: +- Words ending in -tion, -ment, -ance, -ence, -al, -ity, -ness in subject position +- Phrases like "make a decision," "conduct an analysis," "give consideration to" + +Rewrites: +- "Make a decision" → "decide" +- "Conduct an analysis of" → "analyze" +- "Give consideration to" → "consider" +- "Reach an agreement" → "agree" +- "Have a discussion about" → "discuss" + +When you spot a nominalization in subject or object position, ask: can I turn it back into a verb and find a real character to do it? + +## Voice and emphasis + +### 3. Active over passive (with exceptions) + +Default to active voice. Use passive only when: +- The agent is unknown ("My car was stolen.") +- The agent is unimportant or obvious +- You need to keep the subject consistent across sentences (cohesion — see below) +- You want to put the agent at the end of the sentence for emphasis (stress position) + +Active voice puts the character first, where the reader expects to find it. + +### 4. Stress position: end of sentence carries weight + +Readers feel the natural emphasis of a sentence at its end. Put the most important new information there. + +- Weak: *"Climate change is the most pressing issue facing humanity, in my opinion."* +- Strong: *"In my opinion, the most pressing issue facing humanity is climate change."* + +- Weak: *"Agenta is the AI reliability layer that closes that gap, fundamentally."* +- Strong: *"The gap is what Agenta closes."* + +When revising, ask: what's the most important word or idea in this sentence? Is it landing in the stress position? + +## Cohesion across sentences + +### 5. Old before new + +Each sentence should start with information the reader already knows (from the previous sentence or shared context) and end with new information. This creates a chain readers can follow effortlessly. + +- Choppy: *"Photosynthesis converts sunlight to energy. The Calvin cycle is the second stage of photosynthesis. Carbon fixation happens in the Calvin cycle."* +- Cohesive: *"Photosynthesis converts sunlight to energy. The second stage of photosynthesis is the Calvin cycle, which fixes carbon."* + +In the cohesive version, each sentence picks up where the last one left off. + +### 6. Topic strings (consistent subjects across a paragraph) + +A paragraph has a "topic string" — the chain of grammatical subjects across its sentences. When the topic string is consistent, the paragraph feels unified. When subjects keep changing, the paragraph feels scattered. + +Diagnostic: list the grammatical subject of each sentence in the paragraph. If the list is "team / data / system / users / process / our approach," the paragraph has no topic string. Pick one anchor character (often the most important agent in the paragraph) and rewrite so most sentences share that subject. + +This is what passive voice is good for: it lets you keep the same subject across sentences even when the action changes hands. + +### 7. Topic + body + close in paragraphs + +Each paragraph should: +- Open with a controlling sentence (the issue or claim) +- Develop it in the body +- Close with a sentence that points forward, names the consequence, or summarises + +Don't bury the controlling idea in the middle. The opening sets the topic; the close earns the stress position. + +## Concision + +### 8. Cut what you don't need + +Williams' favourite categories of cuts: + +**Wordy phrases:** +- "due to the fact that" → "because" +- "in order to" → "to" +- "at this point in time" → "now" +- "for the purpose of" → "to" +- "in the event that" → "if" +- "with regard to" → "about" +- "the fact that" → usually deletable + +**Doublets** (keep one of each pair): +- "each and every" +- "first and foremost" +- "any and all" +- "true and accurate" + +**Empty modifiers:** +- very, really, basically, actually, literally, essentially, simply, quite, rather + +**Throat-clearing openers:** +- "I think that..." +- "It should be noted that..." +- "It is important to remember that..." + +**Redundant pairs:** +- "free gift" (gifts are free) +- "advance planning" (planning is in advance) +- "end result" (results are at the end) + +### 9. Sentence length: vary it on purpose + +Mix short and long sentences. A short sentence after a long one creates emphasis. A run of short sentences in a row gets choppy. A run of long sentences in a row gets exhausting. + +Read your prose aloud. The rhythm should breathe. + +## Grace (the optional layer) + +### 10. Parallel structure + +When you list or contrast, use parallel grammatical structure so the reader sees the parallel meaning. + +- Bad: *"She likes hiking, swimming, and to bike."* +- Good: *"She likes hiking, swimming, and biking."* + +- Bad: *"The product is fast, reliable, and you can scale it."* +- Good: *"The product is fast, reliable, and scalable."* + +### 11. Balanced sentences + +Two parallel halves separated by a comma, semicolon, or colon create rhythm and emphasis. + +- *"Demos are easy. Reliability isn't."* +- *"They iterate on prompts; the system iterates on them."* + +Use sparingly. Overused, balance becomes mannered. + +### 12. End on the strongest word + +When you have a choice, arrange the sentence so the strongest word lands last. The reader's ear hears it as the point. + +## Ethics + +### 13. Write to others as you'd want them to write to you + +Avoid: +- Jargon that excludes readers who don't share your specialty +- Hedges that obscure responsibility ("mistakes were made") +- Complexity used to signal authority rather than clarify +- Vague language that lets you avoid commitment + +If you'd be frustrated reading what you've written, revise. + +## A working diagnostic checklist + +When editing a draft, run through: + +1. **Subject test.** What is the grammatical subject of each sentence in the paragraph? Is there a topic string? If not, pick an anchor character and rewrite. +2. **Verb test.** Are the verbs concrete actions, or weak constructions ("is," "has," "makes," "does")? Look for nominalizations to convert back to verbs. +3. **Voice test.** Each passive sentence: is it passive for a reason? If not, flip to active. +4. **Stress position test.** What word ends each sentence? Is it the most important word, or a throwaway? +5. **Cut test.** Read each sentence and ask: which words can I delete without losing meaning? Cut them. +6. **Length test.** Read aloud. Does the rhythm vary? Do any sentences run on or chop short without purpose? +7. **Reader test.** If you were the reader, would you understand this on first read? + +## When to apply this skill + +- Drafting any prose where clarity matters: technical writing, sales copy, internal memos, exec summaries, blog posts, documentation +- Editing or revising prose that feels dense, abstract, or passive +- Diagnosing why a paragraph feels off +- When the user references Williams, *Style: Lessons in Clarity and Grace*, *Style: The Basics of Clarity and Grace*, "old-before-new," "topic string," or "stress position" + +This skill complements `ai-writing-tropes` (which lists patterns to avoid). Williams gives the positive principles; tropes gives the negative ones. + +## Sources + +- Williams, Joseph M. and Bizup, Joseph. *Style: Lessons in Clarity and Grace*. (Ten editions, the foundational text.) +- Williams, Joseph M. *Style: The Basics of Clarity and Grace*. (Condensed, paperback companion.) +- Williams, Joseph M. *Style: Toward Clarity and Grace*. (Earlier title in the same family.) diff --git a/.claude/skills/update-api-docs/SKILL.md b/.agents/skills/update-api-docs/SKILL.md similarity index 100% rename from .claude/skills/update-api-docs/SKILL.md rename to .agents/skills/update-api-docs/SKILL.md diff --git a/.claude/skills/update-llm-model-list/SKILL.md b/.agents/skills/update-llm-model-list/SKILL.md similarity index 100% rename from .claude/skills/update-llm-model-list/SKILL.md rename to .agents/skills/update-llm-model-list/SKILL.md diff --git a/.agents/skills/write-issue/SKILL.md b/.agents/skills/write-issue/SKILL.md new file mode 100644 index 0000000000..395d259d1f --- /dev/null +++ b/.agents/skills/write-issue/SKILL.md @@ -0,0 +1,131 @@ +--- +name: write-issue +description: Write and file Linear issues (bugs and feature requests) the Agenta way. Use when the user asks to create, file, or draft a Linear or GitHub issue, write a bug report or feature request, or turn a problem into a tracked issue. Covers the title format, reproduction-first structure, when to use a todo list, and the team/project/label/priority/state conventions, plus filing it through the Linear MCP so the linked GitHub issue is auto-created and the PR links back. +allowed-tools: Read, Edit, Write, Grep, Glob, Bash +user-invocable: true +--- + +# Write Issues + +Write issues a teammate can act on without asking you follow-up questions. Lead with what +the reader needs to reproduce or understand the request, not with your analysis. + +Show a draft first and let the user react before you create anything in Linear. + +## 1. Title + +Prefix the title with the type in parentheses, the same way the repo prefixes PRs. + +- `(bug)` for something broken. +- `(feat)` for a new capability or improvement. +- Other types as needed: `(chore)`, `(docs)`. + +State the symptom or the request in plain words. Keep it short. + +- Good: `(bug) Feedback sent via the API can't be filtered in observability` +- Good: `(feat) Filter evaluation results by metric value` +- Bad: `(bug) Annotation filter options array empty due to thin refs` (that is the root cause, not the symptom) +- Bad: `Observability issue` (vague) + +## 2. Body — bugs + +Do not open with a "Context" heading. Start with the reproduction, in the user's voice: +when I do this, I expect that, but instead this happens. Or: this code is supposed to do +X, but it does Y. Keep the words simple. + +Then give the concrete information a teammate needs to debug it, when you have it: + +- Exact steps to reproduce, numbered. +- Requests and responses (the call you made and what came back). +- Errors, console output, or relevant log lines. +- Screenshots or screen recordings. +- Where it reproduces (local, preview, Railway, cloud) and the version if known. + +That is the whole job: make it reproducible. Include real payloads over descriptions of +them. + +## 3. Do not write the root cause + +The issue tracks the problem, not the investigation. Do not add a "root cause" or "why +this happens" section. That analysis belongs in the PR that fixes it (see the +`write-pr-description` skill). Keep the issue about observable behavior and the +information needed to debug it. + +If you already know the cause, it still does not go in the issue body. Put it in the PR. + +## 4. Body — feature requests + +Lead with the problem or the goal from the user's point of view: what they are trying to +do and why it is hard today. Then describe the behavior they want. Skip implementation +design unless the user asked for it. + +## 5. Todo list + +Add a checkbox list only when delivery is split across stacked PRs or has several ordered +steps. One line per step, written as an outcome. + +``` +- [ ] Fix the filter so it reads the evaluator's real feedback metrics. +- [ ] Fix how the frontend reads the feedback type so the nested schema is understood. +``` + +If a single PR closes the whole issue, skip the todo list. Do not pad an issue with +checkboxes for its own sake. + +## 6. Linear fields + +File issues on the **Agenta** team (key `AGE`). Pick the fields deliberately. + +**Project** (set one): +- **Bugs** — the default home for bug reports. +- **Quality of life improvements** — small improvements that do not belong to a feature project. +- The active feature project when the work is part of one (for example Annotation Queues, + Core Loop Improvements, Reliability Availability Scalability & Performance, Documentation, + New integrations for observability, DevSecOps & DevEx). List active projects with + `mcp__linear-server__list_projects` and match by area. + +**Labels** (combine a type label with the relevant area labels): +- Type: `Bug Report`, `Feature Request`, `Question`, `Chore`, `refactoring`, `tech-debt`. + Use `unconfirmed bug` or `reproduction-needed` when you could not reproduce it yet. +- Area: `frontend`, `Backend`, `SDK`, `API`, `observability`, `Tracing`, `Workflows`, + `evaluation`, `human evaluation`, `playground`, `prompt management`, `Services`, + `database`, `infrastructure`, `integration`, `security`, `analytics`. +- UX: `UX`, `ux bug`, `dev experience`. +- Visibility: `Public` marks an issue mirrored to the public GitHub repo. This is the label + the GitHub sync watches, so set it when you want the linked GitHub issue created (see + section 7). Use `Core Team` / `Internal Team` for internal-only issues. + +**Priority** (`0` None, `1` Urgent, `2` High, `3` Medium, `4` Low): +- `1` Urgent: data loss, outage, or drop-everything. +- `2` High: important and should land soon. +- `3` Medium: the default for a normal bug. +- `4` Low / `0` None: minor or nice-to-have. + +**State** flow: `Todo` → `In Progress` → `In Review` → `In QA` → `Done`. Use `Backlog` for +later, `Canceled` / `Duplicate` as needed. New issues start in `Todo`; move to `In Progress` +once work has started. + +## 7. Filing it and linking the PR + +Create with `mcp__linear-server__save_issue` (no `id` field creates a new issue). Pass +`team`, `title`, `description` (Markdown, literal newlines), `project`, `labels`, +`priority`. Link related issues with `relatedTo`, and attach the PR with `links` +(`[{url, title}]`). + +The workspace runs a Linear ↔ GitHub sync that creates a linked GitHub issue when the +`Public` label is set. After creating the Linear issue, find the auto-created GitHub issue +(`gh issue list --repo Agenta-AI/agenta --search ""`, allow a few seconds for the +sync), then link the PR to it by adding `Closes #` (or `Refs #` when the PR is only +part of the issue) to the PR body. The sync then moves the Linear issue as the PR opens and +merges. + +To move the issue yourself, call `save_issue` again with the issue `id` and `state: "In Progress"`. + +## 8. Checklist before you create + +- Title prefixed with `(bug)` / `(feat)` and states the symptom or request, not the cause. +- Bug opens with reproduction in plain words, then steps + real requests/responses/logs. +- No root-cause section. +- Todo list only if the work is stacked or multi-step. +- Team, project, labels, priority set. `Public` added if it should sync to GitHub. +- After creating: GitHub issue found, PR links to it, Linear state set as the user asked. diff --git a/.claude/skills/write-social-announcement/SKILL.md b/.agents/skills/write-social-announcement/SKILL.md similarity index 100% rename from .claude/skills/write-social-announcement/SKILL.md rename to .agents/skills/write-social-announcement/SKILL.md diff --git a/.claude/skills/add-announcement b/.claude/skills/add-announcement new file mode 120000 index 0000000000..6f6631f9b1 --- /dev/null +++ b/.claude/skills/add-announcement @@ -0,0 +1 @@ +../../.agents/skills/add-announcement \ No newline at end of file diff --git a/.claude/skills/create-changelog-announcement b/.claude/skills/create-changelog-announcement new file mode 120000 index 0000000000..a16cd0d0d8 --- /dev/null +++ b/.claude/skills/create-changelog-announcement @@ -0,0 +1 @@ +../../.agents/skills/create-changelog-announcement \ No newline at end of file diff --git a/.claude/skills/implement-feature b/.claude/skills/implement-feature new file mode 120000 index 0000000000..50ceb99a51 --- /dev/null +++ b/.claude/skills/implement-feature @@ -0,0 +1 @@ +../../.agents/skills/implement-feature \ No newline at end of file diff --git a/.claude/skills/plan-feature b/.claude/skills/plan-feature new file mode 120000 index 0000000000..015f20d524 --- /dev/null +++ b/.claude/skills/plan-feature @@ -0,0 +1 @@ +../../.agents/skills/plan-feature \ No newline at end of file diff --git a/.claude/skills/style-editing b/.claude/skills/style-editing new file mode 120000 index 0000000000..fc54c4fc4f --- /dev/null +++ b/.claude/skills/style-editing @@ -0,0 +1 @@ +../../.agents/skills/style-editing \ No newline at end of file diff --git a/.claude/skills/sync-model-catalog b/.claude/skills/sync-model-catalog new file mode 120000 index 0000000000..1dc0d841c2 --- /dev/null +++ b/.claude/skills/sync-model-catalog @@ -0,0 +1 @@ +../../.agents/skills/sync-model-catalog \ No newline at end of file diff --git a/.claude/skills/update-api-docs b/.claude/skills/update-api-docs new file mode 120000 index 0000000000..504aec08c5 --- /dev/null +++ b/.claude/skills/update-api-docs @@ -0,0 +1 @@ +../../.agents/skills/update-api-docs \ No newline at end of file diff --git a/.claude/skills/update-llm-model-list b/.claude/skills/update-llm-model-list new file mode 120000 index 0000000000..fe493e6381 --- /dev/null +++ b/.claude/skills/update-llm-model-list @@ -0,0 +1 @@ +../../.agents/skills/update-llm-model-list \ No newline at end of file diff --git a/.claude/skills/write-issue b/.claude/skills/write-issue new file mode 120000 index 0000000000..402409aa61 --- /dev/null +++ b/.claude/skills/write-issue @@ -0,0 +1 @@ +../../.agents/skills/write-issue \ No newline at end of file diff --git a/.claude/skills/write-social-announcement b/.claude/skills/write-social-announcement new file mode 120000 index 0000000000..6a2d8030ff --- /dev/null +++ b/.claude/skills/write-social-announcement @@ -0,0 +1 @@ +../../.agents/skills/write-social-announcement \ No newline at end of file diff --git a/.gitignore b/.gitignore index 53b7bd01af..39f748bb2c 100644 --- a/.gitignore +++ b/.gitignore @@ -84,13 +84,39 @@ services/runner/tests/results/ .agents/* !.agents/skills/ .agents/skills/* +!.agents/skills/add-announcement/ !.agents/skills/agent-release-gate/ +!.agents/skills/agenta-package-practices/ +!.agents/skills/create-changelog-announcement/ +!.agents/skills/implement-feature/ +!.agents/skills/plan-feature/ +!.agents/skills/style-editing/ +!.agents/skills/sync-model-catalog/ +!.agents/skills/update-api-docs/ +!.agents/skills/update-llm-model-list/ +!.agents/skills/write-docs/ +!.agents/skills/write-issue/ +!.agents/skills/write-pr-description/ +!.agents/skills/write-social-announcement/ !.agents/skills/write-template-playbooks/ !.claude/ .claude/* !.claude/skills/ .claude/skills/* +!.claude/skills/add-announcement !.claude/skills/agent-release-gate +!.claude/skills/agenta-package-practices +!.claude/skills/create-changelog-announcement +!.claude/skills/implement-feature +!.claude/skills/plan-feature +!.claude/skills/style-editing +!.claude/skills/sync-model-catalog +!.claude/skills/update-api-docs +!.claude/skills/update-llm-model-list +!.claude/skills/write-docs +!.claude/skills/write-issue +!.claude/skills/write-pr-description +!.claude/skills/write-social-announcement !.claude/skills/write-template-playbooks # Temporary SDK copies created by run.sh --local