Six processes. Fifteen disciplines. One ticket at a time.
48 steps, each a skill your agent runs. Generated from the workflow data that the skills are built from, so this page and the framework cannot disagree.
A kind of work, not a person or a headcount. One developer runs every discipline on a personal project; a team divides them however it likes.
Step
One unit of work, delivered as a skill and invoked as a command inside your agent. Each names what it reads, what it produces, when that counts as done, and the guidance it follows.
Process
An ordered set of steps toward a goal. The order is a description, never an enforcement: every step can run at any time.
The earlier version of this page described six phases and twenty-three steps with named actors and tools. Actors are gone because the discipline is the actor and the framework never assumes who performs it (T-13); tools are gone because the framework describes the process and lets the agent infer the tool from the project (T-01). That earlier document is kept in the website repository as the historical record of the pre-SDK methodology.
The cycle
The six processes
Conception and idea refinement
From a stakeholder conversation to a refined, prioritised, ticketed backlog with architecture decided.
Exit: Every requirement is a scenario in a feature file, linked to a ticket and a page; the architecture is recorded as decision records; the backlog is prioritised.
Development
From a ready ticket to merged, reviewed code with the tests that prove it.
Exit: Every committed ticket is merged on a branch that references it, with passing tests at each tier the change touched, and the ticket is transitioned.
Testing
From Development's proof of the requirement to a suite that goes beyond it.
Exit: Every scenario has a test at the tier the strategy assigned; gaps found are scenarios and questions; security and performance results are recorded with tickets for every miss.
Deployment
From tested code to production, deliberately and repeatably.
Exit: Production metrics match the baseline or regressions are ticketed; stakeholders have accepted the scenarios by name; usability findings are ticketed.
Maintenance and continuous improvement
Keeping the system healthy, secure, documented, and improving after release.
Exit: Incidents are resolved and reviewed, defects fixed with reproducing tests, feedback turned into roadmap decisions, and security and documentation evidence current.
The framework's own work: bootstrapping a project, checking that the environment and repository meet the declared requirements, and growing the framework through extensions. It is not a software delivery discipline; it is what makes the other fourteen runnable.
Owns:
Aggregating and probing every declared requirement and reporting the result (T-10, T-11)
Bringing a repository up to the framework's requirements with the user's consent
Scaffolding, validating, installing, and sharing extensions (T-02)
Routing the agent to the right discipline and step for the task at hand
Authoring the framework itself: adding opinions, tenets, disciplines, processes, and steps with all of their plumbing (in the aa-sdlc repository only)
Report health /aa-fw-health
Aggregate every requirement declared by the installed skills, plugins, and processes, probe each one, and report what is met, unmet, or not applicable, and what depends on each. Report the install itself. Never block, never change anything.
The installed skills and plugins and the requirements they declare
The merged aa.config.yaml, if a project is in scope
The agent's own tools: which systems it can actually reach
Produces
Health report in returned to the user; written to the documents folder only if asked. Done when:
Every declared requirement appears with a status and, if unmet, what depends on it and the remedy
The install (scope, version, target, skills, commands, update available) is reported
Coverage is reported per discipline and technology, never headcount (T-13)
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
Probe by doing, not by looking. To check the ticket system, read a ticket; to check source control, read the remote; to check the build, run the build script. A configuration file that exists proves nothing.
Probe the ticket project's configuration, not only its names. Read its workflow states, the moves between them, the parent links it allows, and its board; a mapping whose names all exist can still leave two life-cycle states on one workflow state or a step with no move to make (R-43).
Report not-applicable as its own status. A requirement that cannot apply here (hooks on a target with no hooks) is not a failure and must not look like one.
Change nothing. If a probe would need to create, write, or install anything to succeed, report it as unmet and name /aa-fw-init as the remedy.
Group the report by kind (environment, project, tooling, coverage) and lead with required-and-unmet.
Tenets T-10, T-11, T-13
Bootstrap a project /aa-fw-init
Run health, then work through the unmet requirements that need judgement, fixing each with the user's consent, listing what cannot be fixed with its remedy, and running health again.
Bootstrapped project in the repository root and the project config. Done when:
The ticket project was checked against R-41 and R-43 as soon as it was confirmed, before any other fix
Where the ticket project is shared, conventions.ticket.filter selects this project's tickets, and no shared workflow or board was changed without its owner's consent (T-14)
The project's own root page is recorded as conventions.knowledge.root, or the documents folder's knowledge folder is recorded as the knowledge base (R-03)
Feature files that existed before the pages were offered for seeding as pages and pulled back with provenance headers, or R-46 is listed as unmet
The stack is recorded in the project config, inferred from the repository or answered by the user in a survey
Every category the framework and the stack prescribe has a tool recorded under tools, chosen by the user, or is recorded as having none
Every recorded tool is installed on this machine at its minimum version, or its install was declined and is listed
Every fixable unmet requirement was proposed and, if agreed, fixed
Every unfixable unmet requirement is listed with its remedy
A second health report shows what changed and what remains
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
For this step:
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-50 Start each language's static analyser rule set from a published best-practice baseline for the language, framework version, and kind of application, or from a widely used alternative the user picks, or from the user's stated preferences; tailor it in the rule set file rather than with suppressions in code, and record the baseline, its version, and every departure with its reason in a decision record.
Propose, then act. State each fix as a one-line proposal with what it creates or changes, and perform it only after the user agrees. Batch trivial fixes (folders, stubs) into one proposal.
Never choose a tool for the project. When a language has no formatter or a technology has no skill, name the gap and list what is available in the project's scope or as plugins; the user chooses (T-01).
Map before you create. If the repository already has an equivalent of a conventional folder, propose the mapping in the project config rather than a second folder.
Leave stubs honest. A stub root script must say, in its first lines, exactly what it must do when filled in and must exit non-zero until it is.
The ticket project and knowledge base are a conversation, not a lookup. Ask the user; when they name a system and paste a URL, search the agent's own scope for a skill, MCP server, or CLI for that system (T-05), confirm the project through it, and record the mapping. If the connector is absent or unauthorised, say exactly that, record the mapping anyway, and let health report R-02 or R-03. Never name a system the user did not name (T-01). Record this project's ticket filter where the ticket project is shared and its own root page in the knowledge base (T-14); with no knowledge base in scope, offer the documents folder's knowledge folder in the same page format.
Survey only what the repository cannot answer. Infer the stack from what is there; when the repository is blank or leaves it open, ask what is being built, in which languages and frameworks at which versions, for which platforms, deployed where, and built by which pipeline, and record the answers so no one is asked twice.
Record every tool with the command that checks it and the command that installs it on each platform, and put the install in the root initialize script, so the next machine gets the same tools without this conversation.
Check the ticket project the moment it is confirmed, before anything else. Read its workflow, the moves between states, the parent links, and the board, and hold them to R-41 and R-43; propose each missing piece with the step that would stumble on it, make it with consent where the user may administer the project and the workflow is this project's alone, and otherwise list it for the administrator or the shared workflow's owner (T-14). A project that cannot carry the life cycle is found hours later, in the middle of other work, when it is not checked first.
Tenets T-06, T-11
Find what is next /aa-fw-whatsnext
Review the working folder, and the ticket system and knowledge base it links to, against the framework's requirements, opinions, and processes in a fixed order of layers, stop at the first major gap, and name the one thing to do next, usually a command with its arguments. Change nothing.
The working folder, whether or not it is a repository yet
The merged aa.config.yaml, if a project is in scope
The health report: the requirements that are required and unmet
The working tree, the current branch, open merge requests, and the recent commits on the default branch
The decision records, feature files, and tests the recent commits touched
The knowledge base pages under the project's root linked to recent tickets and feature files
The current iteration and the ordered backlog in the ticket system, through the project's ticket filter
Produces
Next-step recommendation in returned to the user; nothing is written. Done when:
Names exactly one gap, the first major one in the layer order, with the evidence that shows it
Names the one thing to do about it, as a command with its arguments where a command fits
Lists the layers checked before it and that each passed, so the user knows what was not found wrong
Says when a layer could not be checked because a system was out of reach, and moves on to the next layer
Ends with the remaining planned work: the open tickets in the current iteration counted by state, or says it could not be read
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
Check the layers in order and stop at the first major gap: foundation (a repository, the project config, the linked ticket project able to carry the life cycle, the knowledge base, and feature files all pulled from their pages), work in flight (uncommitted changes, an unfinished branch, a merge request awaiting review), recent changes held to the opinions (each commit traces to a ticket, code changes carry tests, significant decisions have records, behaviour changes have scenarios on their feature pages, no feature file changed by hand), the knowledge base in step with recent changes, then the next ticket. A later layer cannot be trusted while an earlier one has a gap.
A gap is major when it breaks a required requirement, an opinion on the default branch, or work already started. Anything smaller is not reported; the command answers one question, what to do next, not what could be better.
Take the foundation layer from /aa-fw-health's required-and-unmet findings rather than probing requirements again; health owns requirement checks, and this step owns choosing among them.
Recommend the step that closes the gap, named as its command with its arguments, such as /aa-qa-generate-tests with the ticket id. Where no command fits, say plainly what to do.
Choose the next ticket from the current iteration in priority order, and let its life-cycle state (O-26) choose the command. New is /aa-rf-refine-ticket; Refined is /aa-ip-plan-implementation; Planned is /aa-dev-implement; In review with its change merged is /aa-ba-uat; Accepted is /aa-rel-prepare-release. No iteration is /aa-pm-plan-iteration; an empty backlog is /aa-pd-prioritise.
Change nothing. Read the folder, the tickets, and the pages; do not create, edit, commit, transition, or install anything, even to make a check possible.
Read only what is this project's (T-14). Take its tickets through the ticket filter in the project config and its pages from under its knowledge root; in a shared ticket system or knowledge base, nothing outside them is this project's gap.
When a system is out of reach, say which layer could not be checked and why, and continue with the layers that can be; never report a layer as passed that was not checked.
Walk the user from a need the framework does not cover to a valid, installable extension: choose the kind, scaffold it, declare its requirements, write its feature files, validate it against the tenets, and install or share it.
The installed extensions, to add to rather than duplicate
The organisation config repository, if sharing
Produces
Extension in plugins/<name>/ for packs; the project's skills location for a project skill; targets/<name>/ for an adapter. Done when:
Has a manifest, declared requirements in its own id range, and feature files
Passes validation: changes nothing in core, and core-level guidance names no tool
Installed at the chosen scope, or added to the organisation config repository
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
Fit the kind to the need before scaffolding. A stack-specific practice is a tech-stack pack; a tool the life cycle uses is a tool pack; an organisational gate is a process pack; something only this repository needs is a project skill; a new agent is a target adapter. Explain the choice in one sentence.
A plugin skill attaches to the life cycle. It names the core step or process it serves, or the core requirement it satisfies; a skill that attaches to nothing, such as code generation, script generation, organisation-wide practice, or media generation, is an ordinary agent skill and stays outside the framework.
Write the feature file first. The extension's behaviour is captured as scenarios before any skill text is written, so the skill has something to be checked against.
Refuse politely and specifically. When an extension would change core, name the exact core item and offer the nearest allowed alternative.
Prefer adding to an existing pack over creating a second pack for the same technology or process.
Tenets T-01, T-02, T-11, T-12
Product Management pd
Decides what to build and why, and in what order. Owns the outcome the software is meant to achieve, the measure of whether it did, and the roadmap that sequences the work. Product Management answers "should we", Business Analysis answers "what exactly".
Owns:
The product outcome and success metrics for each initiative, recorded as the anchor epic
Prioritisation of the backlog by value, risk, and dependency
Feedback analysis from users, support, and production data, and the roadmap it produces
The decision to start, pause, or stop an initiative
Define the outcome /aa-pd-define-outcome
Write down what an initiative is meant to achieve and how we will know. Produces the anchor epic with a measurable outcome, so every later step can answer "does this serve the outcome".
Existing roadmap and outcomes, to avoid duplicates and find conflicts
Produces
Anchor epic in the ticket system. Done when:
States the outcome as a change in a measure, not a list of features
Names the success metric, its current value, and the target
Names who benefits and what they can do afterwards that they cannot do now
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-35 Start every requirement from written goals: the outcome, then the scenarios. When a screenshot or mock-up arrives first, treat it as evidence of what someone wants: write the goals and scenarios it implies, record what it does not show as questions on the ticket, get them confirmed, and only then produce a mock-up from them.
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
G-52 Create every ticket as one of the five kinds, in the ticket system's name for it from the project config: an epic for an outcome, a story for one behaviour a user can observe with its scenarios, a task for a buildable piece of a story's plan, a bug for behaviour that contradicts a scenario, a spike for a time-boxed question; link each to its parent (task to story, story to epic).
Outcome, not output. If the statement can be satisfied by shipping something nobody uses, rewrite it until it cannot.
Put a number on it. A metric with no baseline is a wish; measure or estimate the current value and say which.
Say what is out of scope in the same place, so refinement does not have to guess.
Tenets T-04, T-07 | Opinions O-15, O-18
Prioritise the backlog /aa-pd-prioritise
Order epics and stories by value against the outcome, risk, and dependency, and record why. The ordered backlog lives in the ticket system; the reasoning lives on the tickets.
Dependencies and risks surfaced by Refinement, Technical Analysis, and Security
Produces
Ordered backlog in the ticket system. Done when:
Every item has a rank and a one-line reason on the ticket
Items blocked by a dependency are ranked after what blocks them
The top of the backlog is ready or in refinement, not raw ideas
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-28 Before recording a size, write on the ticket how the work will be built (what changes, what is unknown, what could go wrong) at a depth that matches the stakes, and cite that reasoning from the size. If a number is needed before that thinking exists, give a range labelled as a guess, do not record it as the size, and never commit an iteration on it.
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
Rank by outcome contribution first, then risk reduction, then cost. When two items tie, prefer the one that retires an unknown.
Never reorder silently. Every change of rank is a comment on the ticket saying what moved and why, and a demotion of committed work is a decision record (O-18).
Ask before demoting. If an item someone is working on drops out of the iteration, that is a conversation, not a rank change.
Tenets T-04, T-06 | Opinions O-18
Analyse feedback and update the roadmap /aa-pd-iterate
Turn what users, support, and production are saying into decisions: what to enhance, what to fix, what to stop. Produces a feedback analysis and a roadmap update, with new tickets where the answer is "build".
User feedback, support tickets, incident post-mortems, and production metrics
Current roadmap and outcomes
Produces
Product feedback analysis in the knowledge base, linked from the roadmap epic. Done when:
Feedback is grouped by theme with counts and sources, not by who said it loudest
Each theme has a decision: enhance, fix, stop, or wait, with a reason
Roadmap update in the ticket system and the knowledge base. Done when:
Every "enhance" or "fix" decision has a ticket; every "stop" has a closed ticket with the reason
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
Count before you conclude. Compute theme frequencies and metric movements with a tool; do not eyeball a list and call it a trend.
Separate signal from volume. One report from a critical workflow can outrank twenty from a cosmetic one; say so explicitly when you rank that way.
Close the loop. Where feedback came from a ticket, comment on it with the decision.
Tenets T-04, T-07 | Opinions O-18
Business Analysis ba
Turns a business need into requirements the whole team can read and a test can execute. Discovers what stakeholders actually need, closes the gaps, writes it as Gherkin scenarios, and later confirms with those stakeholders that what was built is what they meant.
Owns:
Discovery with stakeholders and the initial requirements it produces
Gap analysis, the question log, and getting questions answered
Requirements as scenarios in feature files, linked to tickets and pages (T-12, O-01)
User acceptance testing against those scenarios
Run discovery /aa-ba-discover
Capture what stakeholders need, as they say it and as they mean it. Produces the initial requirements as draft scenarios and a question log of everything not yet answered.
Stakeholder input: a conversation, a transcript, a document, or a session with the user
Existing system documentation and the project's feature pages
Any screenshot or mock-up offered as the request, treated as evidence rather than as the requirement (O-15)
Produces
Initial requirements in the knowledge base, as Draft scenarios on feature pages under the project's Requirements section (in the documents folder where no knowledge base is in scope), tagged with the epic. Done when:
Every stated need is a scenario or an explicit non-requirement
Business objectives and scope boundaries appear in the feature description
Every feature and scenario has its id, and the epic links to each page and its scenario ids
Question log in the anchor epic, as open questions. Done when:
Every unanswered question has context and an owner
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-19 Tag every Approved scenario on its feature page with the ticket that asked for it, and link the ticket to the page and the scenario ids.
G-35 Start every requirement from written goals: the outcome, then the scenarios. When a screenshot or mock-up arrives first, treat it as evidence of what someone wants: write the goals and scenarios it implies, record what it does not show as questions on the ticket, get them confirmed, and only then produce a mock-up from them.
G-49 Give every feature a stable id (F-nnn) and every scenario one derived from it (F-nnn-nn), assigned on its feature page once and never renumbered or reused; tag or name every automated test with the ids of the scenarios it proves, so coverage is the set of scenario ids that at least one test names.
Write it as Gherkin from the first pass. A requirement captured in prose has to be translated later and loses something each time; a Draft scenario on a feature page can be wrong in a way everyone can see, and the repository gets it only once it is Approved.
Ask the confirming question, not the leading one. "So when X happens you need Y?" invites agreement; "What happens when X?" invites the truth.
Record what was not said. Silence on error cases, permissions, and edge conditions is a question, not an assumption.
A picture is a witness, not a specification. When the request arrives as a screenshot or mock-up, write the goals and scenarios it implies, log what it does not show as questions, and let the mock-up be regenerated from the confirmed scenarios later (O-15).
Tenets T-04, T-06, T-12 | Opinions O-01, O-15
Refine requirements /aa-ba-refine-requirements
Close the gaps. Turn draft scenarios into complete, unambiguous, testable ones; record the technical constraints they must live within; link every scenario to its ticket and page.
Draft scenarios on their feature pages and the question log from discover
Answers from stakeholders
Technical constraints from Technical Analysis and Security, if available
Produces
Feature pages in the knowledge base under the project's Requirements section (in the documents folder where no knowledge base is in scope). Done when:
Every scenario has concrete Given, When, Then steps with no "should work correctly"
Every scenario the stakeholder confirmed is Approved and tagged with its ticket; the ticket links to the page and the scenario ids
Ambiguities are resolved or recorded as open questions on the ticket
Technical constraints document in the knowledge base, linked from the epic. Done when:
Lists the constraints (platform, integration, compliance, performance) the scenarios must satisfy, each with its source
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-19 Tag every Approved scenario on its feature page with the ticket that asked for it, and link the ticket to the page and the scenario ids.
G-35 Start every requirement from written goals: the outcome, then the scenarios. When a screenshot or mock-up arrives first, treat it as evidence of what someone wants: write the goals and scenarios it implies, record what it does not show as questions on the ticket, get them confirmed, and only then produce a mock-up from them.
G-49 Give every feature a stable id (F-nnn) and every scenario one derived from it (F-nnn-nn), assigned on its feature page once and never renumbered or reused; tag or name every automated test with the ids of the scenarios it proves, so coverage is the set of scenario ids that at least one test names.
G-53 Put each knowledge base page under the project's own root, in the section its content belongs to (Overview, Requirements, Architecture, Operations, Releases, Guides, or the names the project config maps them to), name a requirement page after its feature and its feature id, and when a page is superseded mark it and link to what replaced it rather than deleting it.
One behaviour per scenario. If a scenario needs "and" in its Then to describe two outcomes that could fail independently, split it.
Make it executable in principle. Every step must be something a test could observe; if it cannot be observed, it is not a requirement, it is a hope.
Trace every change. Change the scenario on its feature page first; the ticket's acceptance criteria follow the page and the repository gets the change by pulling it (T-12). Never edit the ticket first, and never edit a feature file.
A scenario is Approved when the stakeholder confirms it, not when it reads well. Until then it stays Draft on the page and never reaches the repository.
Tenets T-07, T-12 | Opinions O-01, O-15
User acceptance testing /aa-ba-uat
Confirm with the people who asked for it that what was built is what they meant. Walks stakeholders through the scenarios against the built software and records acceptance or the gap.
The feature files for the ticket or release, freshly pulled from their feature pages
A deployed environment the stakeholder can use
The tests Development and Testing wrote, as evidence
Produces
UAT test cases in the pulled feature files, as the scenarios themselves, plus a walkthrough order on the ticket. Done when:
Every scenario for the ticket is covered by the walkthrough
UAT results report in the anchor ticket, linked from the knowledge base page. Done when:
Each scenario is marked accepted or not, by whom, with the gap described where not
Every gap is a new ticket or a scenario change, never a note that fades
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-51 Move a ticket to a life-cycle state only in the step that produces its evidence, and write that evidence on the ticket as it moves: Refined when its scenarios are linked and the revision recorded, Planned when the plan is confirmed and sized, In progress when work starts on its branch, In review when its merge request is open, Accepted when the stakeholder confirms it, Done when it is released; use the ticket system's names for the states as the project config maps them.
Test the scenario, not the demo. Walk the stakeholder through the Given, When, Then as written; if they want something else, that is a requirement change, and it goes through the feature page.
A gap is not a failure of the build if the scenario was met. Record it as a new requirement so Development is not blamed for a discovery miss.
Record acceptance by name. "Accepted by the product owner on this date" is evidence; "UAT passed" is not.
Tenets T-06, T-07, T-12
UX Design ux
Makes requirements tangible before they are built and checks the result against real use afterwards. Produces mockups and prototypes that stakeholders react to, and reviews the built software for how people actually interact with it.
Owns:
Mockups and interactive prototypes for requirements with a user interface
Interaction and flow design: what the user does, in what order, and what they see
Usability review of built features and the tickets it raises
Prototype /aa-ux-prototype
Make the requirement visible before it is built. Produces mockups and, where the interaction matters, an interactive prototype that stakeholders can react to, and feeds what they say back into the scenarios.
The confirmed (Approved) scenarios for the ticket or epic, pulled from their feature pages; a mock-up is made from them, never before them (O-15)
Existing design system or conventions in the project, if any
The technical constraints document
Produces
Mockups in the documents folder or the design tool the project uses, linked from the ticket and page. Done when:
Every scenario with a user interface has at least one mockup showing its When and Then
Every mockup names the scenarios it renders (O-15)
Variations are labelled with what question each answers
Interactive prototype in linked from the ticket. Done when:
Covers the primary flow end to end; a stakeholder can complete the scenario's When without help
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-35 Start every requirement from written goals: the outcome, then the scenarios. When a screenshot or mock-up arrives first, treat it as evidence of what someone wants: write the goals and scenarios it implies, record what it does not show as questions on the ticket, get them confirmed, and only then produce a mock-up from them.
G-36 Generate every mock-up from confirmed scenarios and name on it the scenarios it renders. Behaviour a mock-up shows that no scenario states is a question on the ticket, not a requirement; change the scenario first, then the mock-up (T-12).
Prototype the flow, not the pixels. The question a prototype answers is "is this the right interaction", and polish hides that question.
Scenarios first, always. If asked for a mock-up with no confirmed scenarios behind it, write or request them first; a mock-up that shows behaviour no scenario states is a question on the ticket, not a requirement (O-15).
Show the unhappy path. A mockup that only shows success leaves the error states to be invented at implementation time.
Feed changes back through the feature page. If the prototype review changes what the user needs, propose the change to the scenario on its page for its owner to approve, then change the prototype (T-12).
Tenets T-06, T-12 | Opinions O-15
Review interaction /aa-ux-review-ux
Use the built software the way a user would and record where the interaction fails the scenario, the prototype, or plain sense. Raises tickets for what it finds.
The scenarios, freshly pulled from their feature pages, and the prototype
Produces
Usability findings in the anchor ticket and the knowledge base page. Done when:
Each finding names the scenario or flow, what was expected, what happened, and the severity
Each finding with severity above cosmetic is a ticket
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-36 Generate every mock-up from confirmed scenarios and name on it the scenarios it renders. Behaviour a mock-up shows that no scenario states is a question on the ticket, not a requirement; change the scenario first, then the mock-up (T-12).
Follow the scenario literally first, then wander. The literal pass finds what was missed; the wander finds what was never imagined.
Distinguish defect from design. "It does not do what the scenario says" goes to Development; "the scenario was wrong" goes to Business Analysis as a requirement change.
Tenets T-07 | Opinions O-15
Technical Analysis ta
Decides how the system will be shaped and records why. Produces the architecture, the technology choices, and the decision records that let anyone later understand what was considered and rejected. Investigates unknowns with time-boxed spikes rather than guesses.
Owns:
System architecture and its diagrams
Technology stack choices and the constraints they impose
Decision records for every significant technical decision (G-41)
Time-boxed spikes to resolve technical unknowns
Architect /aa-ta-architect
Decide the shape of the system for an epic or initiative: components, boundaries, integrations, data, and the technology stack, each with the reason. Produces the architecture and the decision records that back it.
The feature pages the epic links to, pulled as feature files, and the technical constraints document
The existing architecture and decision records
Organisational standards from the enterprise or team scope
Produces
System architecture in the documents folder, linked from the knowledge base page and the epic. Done when:
Shows components, their responsibilities, and every integration boundary
Every scenario can be traced to the components that satisfy it
Every component, boundary, and extension point names the scenario that requires it or the decision record that justifies it (O-20)
Technology stack document in the knowledge base. Done when:
Every technology choice has a decision record
Constraints imposed on Development and Operations are explicit
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-23 State a time box for any open-ended investigation before starting it, stop when it is reached, and report what was found either way.
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
G-43 Design for the scenarios that exist, not the ones you expect: choose the simplest structure that satisfies them, and add an abstraction, extension point, configuration option, or feature only when a scenario requires it or a decision record justifies it, naming which. In review, code or structure that serves no scenario is a finding, and so is a fourth copy of the same code where one named thing would do.
G-53 Put each knowledge base page under the project's own root, in the section its content belongs to (Overview, Requirements, Architecture, Operations, Releases, Guides, or the names the project config maps them to), name a requirement page after its feature and its feature id, and when a page is superseded mark it and link to what replaced it rather than deleting it.
Decide the fewest things that let work start. Every decision made before it is needed is a decision made with the least information.
Name the alternatives you rejected. An architecture without rejected options is a preference, not a decision (G-41).
Constrain, do not prescribe. Say what a component must guarantee, not how its code must look; the how belongs to Implementation Planning and the stack.
Tenets T-01, T-04 | Opinions O-04, O-18, O-20
Record a decision /aa-ta-decide
Record one significant technical decision: the context, the options, the choice, and the consequences, so the next person can understand it without asking. Standalone so that decisions made mid-implementation are captured too.
The decision to be made or just made, and the anchor ticket it arose from
Existing decision records that touch the same area
Produces
Decision record in the knowledge base, or the documents folder as a numbered record, linked from the ticket. Done when:
States context, options considered, the decision, and consequences
Is numbered next in the repository sequence, dated, and immutable once accepted; a reversal is a new record that supersedes it and links back (O-18)
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
G-43 Design for the scenarios that exist, not the ones you expect: choose the simplest structure that satisfies them, and add an abstraction, extension point, configuration option, or feature only when a scenario requires it or a decision record justifies it, naming which. In review, code or structure that serves no scenario is a finding, and so is a fourth copy of the same code where one named thing would do.
G-53 Put each knowledge base page under the project's own root, in the section its content belongs to (Overview, Requirements, Architecture, Operations, Releases, Guides, or the names the project config maps them to), name a requirement page after its feature and its feature id, and when a page is superseded mark it and link to what replaced it rather than deleting it.
Short enough to read, complete enough to trust. One screen. If it needs more, the decision is several decisions.
Record the losing options with the same care as the winner; the next person will ask about them first.
Write it when it happens. A decision reconstructed a month later is a story, not a record.
Tenets T-04 | Opinions O-04, O-18, O-20
Spike /aa-ta-spike
Resolve a technical unknown with a time-boxed investigation that produces an answer, not a product. Throwaway code is expected; the finding is the artifact.
The question the spike must answer, stated on the ticket
The time box
Produces
Spike finding in the anchor ticket, with a decision record if the finding decides something. Done when:
Answers the stated question, or states why it could not and what would
Names what was tried, what was learned, and what to do next
Spike code is clearly marked as not for production and is not merged to the main branch
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-23 State a time box for any open-ended investigation before starting it, stop when it is reached, and report what was found either way.
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
G-52 Create every ticket as one of the five kinds, in the ticket system's name for it from the project config: an epic for an outcome, a story for one behaviour a user can observe with its scenarios, a task for a buildable piece of a story's plan, a bug for behaviour that contradicts a scenario, a spike for a time-boxed question; link each to its parent (task to story, story to epic).
Write the question before the code. A spike without a question becomes a prototype without a purpose.
Stop at the time box. Report what you have; an unanswered question with evidence is more useful than a late answer.
Never let spike code become the implementation by accident. If it is good enough to keep, that is a decision to record and a ticket to implement properly.
Tenets T-07 | Opinions O-18
Security sec
Finds what could go wrong before an attacker does. Threat models the architecture, turns the mitigations into requirements, tests the built system for the weaknesses that matter, and keeps dependencies, secrets, and compliance evidence current over the life of the system.
Owns:
Threat models and the security requirements they produce as scenarios
Security testing of the built system and the compliance report
Dependency and secret hygiene, patching, and compliance audit evidence
Threat model /aa-sec-threat-model
Work through what could go wrong with the architecture from an attacker's view, decide which threats matter, and turn each mitigation into a security requirement as a scenario and a ticket.
The system architecture and technology stack document
The feature pages the epic links to, pulled as feature files, for data flows and trust boundaries
Organisational security standards from the enterprise scope, if any
Produces
Threat model in the knowledge base, linked from the epic. Done when:
Every trust boundary and data flow in the architecture is considered
Every threat is rated and has a decision: mitigate, accept, or transfer, with a reason
Security requirements in the feature pages in the knowledge base as scenarios, and the backlog as tickets. Done when:
Every mitigation is a scenario a test can verify and a ticket someone can build
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-19 Tag every Approved scenario on its feature page with the ticket that asked for it, and link the ticket to the page and the scenario ids.
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
Follow the data. Start from what is valuable and trace how it moves; threats appear at every boundary it crosses.
Accept explicitly. An accepted risk with a named owner and a reason is a decision; an unmentioned risk is a surprise.
Make mitigations testable. "Validate input" is not a requirement; "Given a payload over the size limit, then the request is rejected with a logged event" is.
Tenets T-07, T-11, T-12 | Opinions O-18
Security test /aa-sec-security-test
Test the built system for the weaknesses the threat model and common weakness classes predict, and produce evidence for the compliance report. Raises tickets for what it finds.
Security test results in the anchor ticket, with the run output in the documents folder or test system. Done when:
Every security scenario has a result; every finding has a severity and a ticket
Findings are reproducible from the recorded steps
Security compliance report in the knowledge base. Done when:
Maps each control the organisation requires to the evidence that it is met, or the ticket that will meet it
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
Test against the model first, the checklist second. The threat model says what matters here; the checklist says what matters everywhere.
Never test a production system without written permission on the ticket. Prefer a production-like environment.
Report findings without drama and without softening. Severity comes from impact and likelihood, not from how it will be received.
Tenets T-06, T-07
Maintain security and compliance /aa-sec-maintain-security
Keep the system safe after release: patch dependencies, rotate and remove secrets, review access, and keep the compliance evidence current. Recurring; each run anchors on a maintenance ticket.
Dependency and vulnerability reports from the project's tooling
The compliance report and the controls it must evidence
Secrets and access inventories where the project keeps them
Produces
Security patch log in the knowledge base, with each patch as a ticket. Done when:
Every known vulnerability above the agreed threshold is patched, accepted with a reason, or ticketed with a date
Compliance audit evidence in the knowledge base. Done when:
Every control has current evidence or an open ticket
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
For this step:
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-38 Never commit a secret value. Commit a configuration template that names every key with a placeholder for each secret, and record in the development environment configuration where each secret comes from and how a fresh clone obtains it.
Patch in small, tested steps. A dependency update is a change like any other: branch, test, review, merge (G-08). Make it with the package manager so the lock file and transitive graph move together; never edit a version by hand (O-22).
Never commit, log, or paste a secret, including in the report of having found one. Reference where it was, not what it was.
Treat "no findings" as a finding to verify. Confirm the scanner ran against the current code before reporting clean.
Tenets T-07 | Opinions O-16, O-22
Refinement rf
Turns requirements and priorities into a backlog of tickets that are ready to plan and build. Every ticket that leaves Refinement has scenarios, acceptance criteria, and a size, and is small enough to finish in one iteration.
Owns:
Breaking epics into stories and tasks in the ticket system
Making a single ticket ready: scenarios linked, acceptance criteria checkable, size agreed
The definition of ready, and holding tickets to it
Break work into tickets /aa-rf-plan-work
Turn an epic and the scenarios on its feature pages into stories and tasks in the ticket system, each small enough to finish in one iteration, each linked to the page and the scenarios it delivers.
The anchor epic, its outcome, and its feature pages in the knowledge base
The architecture and technical constraints
Priority from Product Management
Produces
Stories and tasks in the ticket system, as children of the epic. Done when:
Every Approved scenario on the epic's feature pages is linked to exactly one story, which links to its page and names the scenario ids
Every such scenario carries its story's ticket tag on its feature page (G-19)
Every story can be finished in one iteration by one person or agent
Dependencies between stories are recorded as links, not prose
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-19 Tag every Approved scenario on its feature page with the ticket that asked for it, and link the ticket to the page and the scenario ids.
G-28 Before recording a size, write on the ticket how the work will be built (what changes, what is unknown, what could go wrong) at a depth that matches the stakes, and cite that reasoning from the size. If a number is needed before that thinking exists, give a range labelled as a guess, do not record it as the size, and never commit an iteration on it.
G-52 Create every ticket as one of the five kinds, in the ticket system's name for it from the project config: an epic for an outcome, a story for one behaviour a user can observe with its scenarios, a task for a buildable piece of a story's plan, a bug for behaviour that contradicts a scenario, a spike for a time-boxed question; link each to its parent (task to story, story to epic).
Split by scenario, not by layer. A story that delivers one scenario end to end can be tested; a "backend story" and a "frontend story" cannot until both are done.
Keep the epic's outcome on every story. A story that cannot say which outcome it serves is either mis-filed or unnecessary.
Do not invent requirements while splitting. A gap found here goes back to Business Analysis as a question, not forward as a guess.
Tenets T-04, T-08, T-12
Make a ticket ready /aa-rf-refine-ticket
Bring one ticket to the definition of ready: scenarios linked and complete, acceptance criteria checkable, size agreed, dependencies clear, questions answered or owned.
The ticket and its linked scenarios on their feature pages
Open questions on the ticket
The team's definition of ready from the project config or knowledge base
Produces
Ready ticket in the ticket system. Done when:
Meets every item of the definition of ready, or says which item it does not and why it proceeds anyway
Acceptance criteria are the scenarios, not a restatement of them
Size is recorded with the implementation thinking that grounds it, and cites it
Records the repository revision and the feature page versions the scenarios were checked against (O-13, G-54)
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-28 Before recording a size, write on the ticket how the work will be built (what changes, what is unknown, what could go wrong) at a depth that matches the stakes, and cite that reasoning from the size. If a number is needed before that thinking exists, give a range labelled as a guess, do not record it as the size, and never commit an iteration on it.
G-31 When a ticket is refined or its plan is confirmed, record on the ticket the repository revision its scenarios and plan were checked against.
G-51 Move a ticket to a life-cycle state only in the step that produces its evidence, and write that evidence on the ticket as it moves: Refined when its scenarios are linked and the revision recorded, Planned when the plan is confirmed and sized, In progress when work starts on its branch, In review when its merge request is open, Accepted when the stakeholder confirms it, Done when it is released; use the ticket system's names for the states as the project config maps them.
Read the scenarios before the ticket description. The description is what someone thought; the scenarios are what was agreed.
Size from the thinking, not the title. Before putting a number on it, write on the ticket what changes, what is unknown, and what could go wrong, at a depth that matches the stakes; a sentence for a small change, a full plan-implementation for a large one (O-10).
A ticket with an unanswered question that changes the scope is not ready, however small it looks.
Tenets T-04, T-07 | Opinions O-10, O-13
Project Management pm
Keeps the work flowing and visible. Plans iterations against capacity, reports status from the ticket system rather than from memory, and runs retrospectives that turn what happened into what changes next.
Owns:
Iteration planning: what is committed, against what capacity
Status reporting derived from the ticket system and source control
Retrospectives and the improvement backlog they produce
Impediment tracking and escalation
Plan an iteration /aa-pm-plan-iteration
Commit a set of ready tickets to an iteration against known capacity, in priority order, and record the commitment and the risks in the ticket system.
Capacity for the iteration, whatever unit the team uses
Carry-over from the previous iteration and its reasons
Produces
Iteration plan in the ticket system, as the iteration or milestone with its committed tickets. Done when:
Committed size does not exceed capacity, or the overage is explicit and agreed
Every committed ticket is ready; none is blocked by an uncommitted one
Risks and assumptions are recorded on the iteration
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-28 Before recording a size, write on the ticket how the work will be built (what changes, what is unknown, what could go wrong) at a depth that matches the stakes, and cite that reasoning from the size. If a number is needed before that thinking exists, give a range labelled as a guess, do not record it as the size, and never commit an iteration on it.
Fill in priority order and stop at capacity. Do not pull a lower item over a higher one because it is smaller unless the higher one is blocked.
Capacity is computed, not felt. Use the team's actual completed size from recent iterations, calculated with a tool (G-02).
Commitment is a proposal until the people doing the work agree; present it and ask.
Tenets T-06, T-07, T-13
Report status /aa-pm-status
Produce a status report for an iteration, epic, or release from the ticket system and source control, not from memory or opinion: done, in progress, blocked, at risk, and why.
Source control activity: branches, merge requests, and their state
The previous status report, for what changed
Produces
Status report in returned to the user; posted to the knowledge base or the iteration ticket if asked. Done when:
Every claim traces to a ticket or a merge request
Blocked and at-risk items name the blocker and who owns unblocking it
Says what changed since the last report
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
Count with a tool and quote the count. "Most tickets are done" is not status; "14 of 19 committed tickets are done, 3 in review, 2 blocked" is.
Report the blocked item before the finished ones. The reader can act on a blocker; they cannot act on praise.
Say what you could not see. If a system was unreachable, the report says so rather than silently omitting it.
Tenets T-04, T-07
Run a retrospective /aa-pm-retrospective
Look at what actually happened in an iteration, release, or quarter, using the record rather than recollection, and turn it into a small number of concrete improvements with owners and tickets.
Ticket system history: cycle times, carry-over, blockers, reopened tickets
Incident and post-mortem records for the period
Input from the people involved, where the user provides it
Produces
Workflow health report in the knowledge base. Done when:
States what the data shows before what people felt, and distinguishes the two
Names the top three things to keep and the top three to change
Process improvement backlog in the ticket system. Done when:
Every "change" is a ticket with an owner and a way to tell whether it worked
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
Measure first, then ask. Present the numbers before opinions so the discussion is about causes, not impressions.
Three changes, not thirty. An improvement backlog nobody works is a complaint log.
Check the last retrospective's changes first. If they were not done, that is the first finding.
Tenets T-07, T-13 | Opinions O-18
Implementation Planning ip
Plans how one ticket will be built before anyone builds it. Reads the scenarios, the architecture, and the code that exists, and writes a plan the ticket carries: what changes, where, in what order, with what tests, and what could go wrong.
Owns:
The implementation plan on the anchor ticket
Breaking a plan into tasks when the ticket is too large to plan as one change
Identifying risks, unknowns, and dependencies before build starts
Plan an implementation /aa-ip-plan-implementation
Before building a ticket, write down how: which files and components change, in what order, what tests prove each step, what could go wrong, and what is still unknown. The plan lives on the ticket and is confirmed before build starts.
The ready ticket, its scenarios, and the implementation thinking its size was based on
The architecture, decision records, and technical constraints
The current code, read, not remembered
What changed in the linked feature pages, their feature files, and the code since the ticket was refined (O-13)
Produces
Implementation plan in the anchor ticket. Done when:
Lists the changes in build order, each with the test that proves it
Names the risks and unknowns, and how each will be resolved or accepted
Says which tiers of test the change touches (O-07)
Confirmed by the user or the ticket owner before implement runs
Records the repository revision and the feature page versions it was written against (O-13)
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-23 State a time box for any open-ended investigation before starting it, stop when it is reached, and report what was found either way.
G-28 Before recording a size, write on the ticket how the work will be built (what changes, what is unknown, what could go wrong) at a depth that matches the stakes, and cite that reasoning from the size. If a number is needed before that thinking exists, give a range labelled as a guess, do not record it as the size, and never commit an iteration on it.
G-31 When a ticket is refined or its plan is confirmed, record on the ticket the repository revision its scenarios and plan were checked against.
G-32 Before starting work on a ticket, compare the repository at the revision recorded on the ticket with the current head, list the changes to the linked feature files and to the files the plan names, and record on the ticket whether the scenarios and plan still hold. A conflict goes back to refinement as a question on the ticket; never absorb it silently or start anyway without saying so.
G-43 Design for the scenarios that exist, not the ones you expect: choose the simplest structure that satisfies them, and add an abstraction, extension point, configuration option, or feature only when a scenario requires it or a decision record justifies it, naming which. In review, code or structure that serves no scenario is a finding, and so is a fourth copy of the same code where one named thing would do.
G-51 Move a ticket to a life-cycle state only in the step that produces its evidence, and write that evidence on the ticket as it moves: Refined when its scenarios are linked and the revision recorded, Planned when the plan is confirmed and sized, In progress when work starts on its branch, In review when its merge request is open, Accepted when the stakeholder confirms it, Done when it is released; use the ticket system's names for the states as the project config maps them.
Read the code you will change before planning the change. A plan written from the architecture diagram alone will meet the real code and lose.
Check the ticket against the repository and the pages first. If the feature pages, the feature files, or the code moved since refinement, say what changed and whether the scenarios still hold before planning against them (O-13).
Plan the tests with the steps. A step with no test is a step you cannot know is done.
Plan the smallest change that makes the scenarios pass. A step that adds an option, a generalisation, or a feature no scenario needs comes out of the plan (O-20).
Prefer the plan that can be abandoned halfway. Order changes so that stopping after any step leaves the system working.
If the plan is longer than the change, the ticket is too big; hand it back to Refinement to split.
Check the size against the plan. If the plan reveals more than the sizing reasoning saw, revise the size on the ticket and say why (O-10).
Tenets T-06, T-07 | Opinions O-10, O-13, O-20
Break a plan into tasks /aa-ip-breakdown-tasks
When a confirmed plan is too large to build as one change, split it into tasks on the ticket, each independently buildable and testable, with their order and dependencies.
Tasks in the ticket system, as children or a checklist of the anchor ticket. Done when:
Each task maps to one or more plan steps and names its test
Order and dependencies are explicit
The sum of the tasks is the whole plan; nothing is left implicit
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-52 Create every ticket as one of the five kinds, in the ticket system's name for it from the project config: an epic for an outcome, a story for one behaviour a user can observe with its scenarios, a task for a buildable piece of a story's plan, a bug for behaviour that contradicts a scenario, a spike for a time-boxed question; link each to its parent (task to story, story to epic).
A task is done when its test passes and its change is committed, not when its code exists.
Keep tasks at a size where the first commit is an hour away, not a day.
Tenets T-07
Development dev
Builds the software and proves it meets the requirement. Every change ships with the tests that show its scenarios pass, is reviewed, and is merged on a branch that references its ticket. Development owns "it works"; Testing owns "and here is what we did not think of".
Owns:
Application code, schema, migrations, and integration code for a ticket
Proving the requirement is met, with unit tests, integration tests, and happy-path end-to-end tests for every scenario the ticket delivers (O-08, G-20)
Code review and merge
Defect fixes, reproduced before fixed
Performance optimisation of existing code
Set up the development environment /aa-dev-setup-environment
Make a fresh clone buildable and testable: fill in the root scripts, configure the tools the stack needs, and record anything a new developer must do by hand.
The stub root scripts from aa init, or the existing scripts
Tech-stack plugins in scope
Produces
Repository structure in the repository root. Done when:
Follows the conventional structure or maps to it in the project config (O-05)
Working root scripts in the repository root. Done when:
initialize, build, test, and pack each run to completion on a fresh clone (O-06)
test accepts a tier parameter and each tier has a home (O-07)
build accepts a lint switch that runs the formatter check and every configured static analyser; each analyser reads a committed rule set whose baseline and departures are in a decision record; languages with no known analyser are recorded in the development environment configuration (O-21)
The e2e tier starts the system and its dependencies in containers from definitions in the repository, where the stack allows (O-12)
Development environment configuration in the documents folder. Done when:
Anything not automated by initialize is written down as a step with a reason
Names where every secret comes from and how a fresh clone obtains it; no secret value is committed (O-16)
Environment-specific settings are in one environment template per environment; functional settings are in the application configuration once; no key is in both (O-25)
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
For this step:
G-29 Put every pipeline step's logic in a root script or a command committed to the repository and call it from the pipeline with the same arguments; when a pipeline step fails, reproduce it locally with that same script before changing anything. A step that can only run in the pipeline is a defect: ticket it and move the logic out.
G-30 Run the end-to-end tier against the system and its dependencies started in containers from definitions committed to the repository, so it runs the same way on any machine and in the pipeline. Reach a shared environment only for a dependency that cannot be containerised, and record which tests depend on it.
G-38 Never commit a secret value. Commit a configuration template that names every key with a placeholder for each secret, and record in the development environment configuration where each secret comes from and how a fresh clone obtains it.
G-48 Split configuration by what varies: settings that differ between environments (endpoints, connection strings, resource names, credentials) go in an environment file or the platform's equivalent, one per environment with a committed template, supplied at deploy time; settings that are the same everywhere (timeouts, limits, behaviour) go in the application configuration committed once with the code. Never put a key in both; when adding a setting, ask which kind it is and put it in that one place, and if a functional setting must differ for one environment, record why in a decision record rather than copying the configuration.
G-50 Start each language's static analyser rule set from a published best-practice baseline for the language, framework version, and kind of application, or from a widely used alternative the user picks, or from the user's stated preferences; tailor it in the rule set file rather than with suppressions in code, and record the baseline, its version, and every departure with its reason in a decision record.
Prove it on a clean clone. Clone to a temporary folder and run initialize, build, test, and pack there before calling it done.
Automate before documenting. A manual step in the documentation is a bug in initialize until it is proven to be impossible to automate.
Do not choose tools the project has not chosen. Use what the stack document, plugins, and existing config name; where nothing does, ask.
Whatever the pipeline will run, make it a script here first. A step that only works on the pipeline runner is a defect (O-11).
The fresh clone is the test. If it needs a file from your machine, a page from the wiki, or a value from your head, commit the template and document the source (O-16).
The anchor ticket and its scenarios, pulled from their feature pages into the feature files (G-54)
The confirmed implementation plan and tasks
The current code, read before it is changed
What changed in the linked feature pages, their feature files, and the files the plan names since the ticket was planned (O-13)
Produces
Application code in source folder, on a branch named per the ticket convention. Done when:
Builds with the root build script, and passes it with the lint switch (O-21)
Every scenario for the ticket has a passing unit test, integration test, and happy-path end-to-end test, as the change warrants each tier
Follows the plan, or the deviation is recorded on the ticket with the reason
No feature file was edited by hand; the feature-file check passes (G-56)
Tests that prove the requirement in unit tests with the project; integration and happy-path end-to-end tests under tests/. Done when:
Happy paths, general permutations, and obvious negative cases are covered (G-20)
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
From the test-writing set: What every step that writes or extends automated tests does: prove with the actual run, and keep every test deterministic and independent.
G-46 Make every test deterministic and independent: inject or freeze time, seed or inject randomness, give each test its own state and clean it up, and replace external dependencies with a container, a fake, or a recorded response; never depend on test order, on state another test left, or on a sleep. A test that fails intermittently is a defect: quarantine it with a ticket the same day, never retry it into green or skip it without one (G-06).
For this step:
G-05 Reproduce a bug with a failing test or a captured observation before changing any code to fix it.
G-17 After three failed attempts at the same fix, stop and reassess the approach rather than trying a fourth variation.
G-20 When implementing a ticket, write the automated tests that prove it: unit and integration tests for every happy path, the general permutations and cases, and the obvious negative cases, plus a happy-path end-to-end test for each scenario. The ticket is not done until they exist and pass.
G-30 Run the end-to-end tier against the system and its dependencies started in containers from definitions committed to the repository, so it runs the same way on any machine and in the pipeline. Reach a shared environment only for a dependency that cannot be containerised, and record which tests depend on it.
G-32 Before starting work on a ticket, compare the repository at the revision recorded on the ticket with the current head, list the changes to the linked feature files and to the files the plan names, and record on the ticket whether the scenarios and plan still hold. A conflict goes back to refinement as a question on the ticket; never absorb it silently or start anyway without saying so.
G-43 Design for the scenarios that exist, not the ones you expect: choose the simplest structure that satisfies them, and add an abstraction, extension point, configuration option, or feature only when a scenario requires it or a decision record justifies it, naming which. In review, code or structure that serves no scenario is a finding, and so is a fourth copy of the same code where one named thing would do.
G-48 Split configuration by what varies: settings that differ between environments (endpoints, connection strings, resource names, credentials) go in an environment file or the platform's equivalent, one per environment with a committed template, supplied at deploy time; settings that are the same everywhere (timeouts, limits, behaviour) go in the application configuration committed once with the code. Never put a key in both; when adding a setting, ask which kind it is and put it in that one place, and if a functional setting must differ for one environment, record why in a decision record rather than copying the configuration.
G-49 Give every feature a stable id (F-nnn) and every scenario one derived from it (F-nnn-nn), assigned on its feature page once and never renumbered or reused; tag or name every automated test with the ids of the scenarios it proves, so coverage is the set of scenario ids that at least one test names.
G-51 Move a ticket to a life-cycle state only in the step that produces its evidence, and write that evidence on the ticket as it moves: Refined when its scenarios are linked and the revision recorded, Planned when the plan is confirmed and sized, In progress when work starts on its branch, In review when its merge request is open, Accepted when the stakeholder confirms it, Done when it is released; use the ticket system's names for the states as the project config maps them.
Check the ticket against the repository and the pages before anything else. Compare the page versions recorded on the ticket with the pages' current versions, and diff from the recorded revision to the head, filtered to the feature files and the files the plan names; record the result on the ticket, and send a conflict back to refinement rather than building on it (O-13).
Write the failing test for the scenario before the code that passes it. Then the code has one job.
Control what varies. Inject or freeze time, seed randomness, own the test data, and fake or containerise external dependencies; a test with a sleep or a live call in it is not finished (O-23).
Stop at every green. Stage the change, write a Conventional Commit message that names its type and its ticket (O-14), present the staged diff and the message, and wait; commit only if the user asked for that commit (O-17).
When the plan meets reality and loses, stop and update the plan on the ticket before continuing. Do not improvise silently.
Never edit a feature file. A scenario found wrong or missing while building is converted to the page format with ConvertTo-FeaturePage and proposed on its feature page for its owner to approve; the repository gets it only by pulling the page once it is Approved (G-18).
Do not widen the change. Adjacent problems become tickets, not fixes on this branch; every hunk on the branch names the ticket, scenario, or decision it serves (O-19).
Change a dependency with the package manager, never by editing a version in a file. If the tool refuses, the refusal goes on the ticket; it is not bypassed (O-22).
Ship the change with what it needs to run: the migration, the new configuration key in every template, the updated runbook. A change that works on your machine because of a file only you have is not done (O-16).
Put each new setting in one place. If its value differs between environments it goes in every environment template; if it does not, it goes in the application configuration once (O-25).
Reproduce a reported defect with a failing test, find the cause, fix the cause, and prove it with the test now passing, on a branch that references the ticket.
The defect ticket: symptoms, environment, steps to reproduce, severity
The scenario the defect violates, if one exists, pulled from its feature page (G-54)
Produces
Reproducing test in the test tier where the defect is observable. Done when:
Fails before the fix and passes after; staged with the fix for the user to commit (O-17)
Fix in source folder, on a branch named per the ticket convention. Done when:
Addresses the cause, not the symptom; the ticket says what the cause was
No existing test was weakened or skipped to make it pass
No feature file was edited by hand; the feature-file check passes (G-56)
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
From the test-writing set: What every step that writes or extends automated tests does: prove with the actual run, and keep every test deterministic and independent.
G-46 Make every test deterministic and independent: inject or freeze time, seed or inject randomness, give each test its own state and clean it up, and replace external dependencies with a container, a fake, or a recorded response; never depend on test order, on state another test left, or on a sleep. A test that fails intermittently is a defect: quarantine it with a ticket the same day, never retry it into green or skip it without one (G-06).
For this step:
G-05 Reproduce a bug with a failing test or a captured observation before changing any code to fix it.
G-17 After three failed attempts at the same fix, stop and reassess the approach rather than trying a fourth variation.
G-29 Put every pipeline step's logic in a root script or a command committed to the repository and call it from the pipeline with the same arguments; when a pipeline step fails, reproduce it locally with that same script before changing anything. A step that can only run in the pipeline is a defect: ticket it and move the logic out.
G-32 Before starting work on a ticket, compare the repository at the revision recorded on the ticket with the current head, list the changes to the linked feature files and to the files the plan names, and record on the ticket whether the scenarios and plan still hold. A conflict goes back to refinement as a question on the ticket; never absorb it silently or start anyway without saying so.
No reproduction, no fix. If it cannot be reproduced, the ticket gets what was tried and goes back for more information.
Find the cause before touching code. Form a hypothesis, test it, and record the result on the ticket; three hypotheses without evidence means stop and reassess (G-17).
If the defect violates no scenario, one is missing. Propose it on its feature page for its owner to approve, never in the feature file; the fix proceeds against it once it is Approved, or the ticket names it as pending approval (G-18).
Review a merge request against its ticket, its scenarios, its plan, and the project's conventions, and record findings on the merge request where the author will see them.
The ticket, its scenarios pulled from their feature pages, and the implementation plan
The feature files on the branch
The build and test results for the branch
Produces
Review findings in the merge request, as comments, with a summary on the ticket. Done when:
Each finding names the file and line, says what is wrong and why, and is marked blocking or not
The review states whether every scenario has a test and whether the plan was followed
Every hunk in the diff traces to a scenario of the ticket or a stated reason; one that does not is a finding (O-19)
A manifest changed without its lock file, or a lock file edited by hand, is a blocking finding (O-22)
A test that depends on order, real time, unseeded randomness, shared state, or a live dependency, or a retry added to a test, is a blocking finding (O-23)
A setting in the wrong place, an endpoint in the application configuration or a timeout in an environment file, is a finding (O-25)
A feature file that fails the feature-file check (no provenance header, a checksum mismatch, or no page that generates it) is a blocking finding; the fix is to change the page and pull it (G-56)
The review says what it did not check
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-43 Design for the scenarios that exist, not the ones you expect: choose the simplest structure that satisfies them, and add an abstraction, extension point, configuration option, or feature only when a scenario requires it or a decision record justifies it, naming which. In review, code or structure that serves no scenario is a finding, and so is a fourth copy of the same code where one named thing would do.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-46 Make every test deterministic and independent: inject or freeze time, seed or inject randomness, give each test its own state and clean it up, and replace external dependencies with a container, a fake, or a recorded response; never depend on test order, on state another test left, or on a sleep. A test that fails intermittently is a defect: quarantine it with a ticket the same day, never retry it into green or skip it without one (G-06).
G-48 Split configuration by what varies: settings that differ between environments (endpoints, connection strings, resource names, credentials) go in an environment file or the platform's equivalent, one per environment with a committed template, supplied at deploy time; settings that are the same everywhere (timeouts, limits, behaviour) go in the application configuration committed once with the code. Never put a key in both; when adding a setting, ask which kind it is and put it in that one place, and if a functional setting must differ for one environment, record why in a decision record rather than copying the configuration.
Read the ticket and scenarios before the diff. A diff reviewed without its purpose is proofread, not reviewed.
Run it. Build and test the branch yourself; do not trust a green badge you did not see produced.
Run the feature-file check on the branch every time. A feature file with no provenance header, a checksum that does not match, or no page that generates it was not pulled from the knowledge base; it blocks the change until the page is changed and pulled (G-56).
Blocking findings are about correctness, security, and the requirement. Style is the formatter's and linter's job, never a review comment (O-21); if a style issue reached review, the finding is that the tools did not run.
Check the commit messages as well as the diff. A commit that does not follow the configured format is a non-blocking finding that names the pattern (O-14).
Report faithfully: "approved" means every scenario has a passing test that you saw run.
Take a branch from "the tests pass" to merged: format changed files, rebase or merge from the target branch, run the full test suite, open or update the merge request linked to the ticket, and transition the ticket.
The project's branch, commit, and merge conventions from the project config
Produces
Merge request in source control, linked from and to the ticket. Done when:
Title and description reference the ticket and summarise the change and its tests; every commit on the branch references the ticket (O-19)
Changed files are formatted; unrelated files are untouched (G-01); the root build passes with the lint switch (O-21)
Full test suite passes on the branch as it will be merged
The feature-file check passes on the branch as it will be merged; every feature file was pulled from its page (G-56)
Every commit on the branch is a Conventional Commit with a type from the project config (O-14), one cohesive change each, made by the user (O-17)
Ticket transition in the ticket system. Done when:
The ticket moves to the state the project uses for "in review" or "done", with the merge request linked
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
For this step:
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-14 Never use a bypass flag on a hook, check, or protected branch. If a gate blocks, fix the cause or tell the user.
G-29 Put every pipeline step's logic in a root script or a command committed to the repository and call it from the pipeline with the same arguments; when a pipeline step fails, reproduce it locally with that same script before changing anything. A step that can only run in the pipeline is a defect: ticket it and move the logic out.
G-51 Move a ticket to a life-cycle state only in the step that produces its evidence, and write that evidence on the ticket as it moves: Refined when its scenarios are linked and the revision recorded, Planned when the plan is confirmed and sized, In progress when work starts on its branch, In review when its merge request is open, Accepted when the stakeholder confirms it, Done when it is released; use the ticket system's names for the states as the project config maps them.
Format only what you changed. Reformatting untouched files hides the change and creates conflicts for everyone else.
Bring the branch up to date before the final test run, and run the whole suite, not the tier you were working in.
Run the feature-file check before opening or merging the request. A feature file that fails it blocks the merge; change the page and pull it, never edit the file (G-56).
Never bypass a hook or a protected-branch rule. If a gate blocks, fix the cause or tell the user (G-14).
Merge only if the project's conventions let you; otherwise open the request and stop (G-13).
Never commit the remaining changes yourself. Stage them, present them, and report that the branch waits on the user's commit (O-17).
Improve the performance of existing code against a measured baseline: profile, change the thing the profile says, measure again, and keep the change only if the measurement improved without breaking a test.
The performance ticket with the target metric and baseline from performance-test
Profiling tools the project uses
Produces
Optimisation implementation report in the anchor ticket. Done when:
Baseline, change, and after measurement are recorded with the method used
The change is on a branch with all tests passing
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
For this step:
G-05 Reproduce a bug with a failing test or a captured observation before changing any code to fix it.
No baseline, no optimisation. Measure first, with a tool, and record the number.
Change one thing per measurement. Two changes measured together teach nothing.
A faster wrong answer is a defect. Every optimisation runs the full suite before it is kept.
Tenets T-07 | Opinions O-19
Testing qa
Makes the test suite as comprehensive as is reasonable. Starts from the scenarios and the tests Development wrote, then applies general testing strategies to find what the requirement did not say. Every gap it finds becomes a question on the ticket and a scenario in the feature file.
Owns:
The test strategy for an epic or release
Tests beyond the stated requirement at every tier: boundaries, states, errors, concurrency, interaction sequences (G-21)
End-to-end and visual regression suites
Performance and load testing and the baseline it establishes
Exploratory testing and the defects and gaps it raises
Write a test strategy /aa-qa-test-strategy
For an epic or release, decide what will be tested at which tier, what will be automated, what needs exploratory or manual attention, what environments and data are needed, and what will not be tested and why.
The feature pages for the scope, pulled as feature files, and the architecture
The risk view from Security and Technical Analysis
Existing suites and their coverage
Produces
Test strategy in the knowledge base, linked from the epic. Done when:
Every scenario is assigned a tier and an approach
Risks are ranked and the highest have the most attention
Out-of-scope items are listed with the reason
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-21 Start from the scenarios pulled from the feature pages, then apply general testing strategies (boundaries, state transitions, error and recovery paths, concurrency, realistic user interaction sequences) to find what the requirement did not say. Record each gap as a question on the ticket and a Draft scenario proposed on its feature page, never in the feature file.
Push tests down. Prove it at the lowest tier that can observe it; end-to-end tests are for what only end-to-end can see.
Name the risks the requirement does not mention. Concurrency, data volume, partial failure, and permissions rarely appear in scenarios and usually appear in incidents.
Tenets T-07 | Opinions O-23
Extend the test suite /aa-qa-generate-tests
Start from the scenarios and the tests Development wrote, then apply general testing strategies to find and test what the requirement did not say. Every gap becomes a question on the ticket and a Draft scenario on the feature page.
The ticket's scenarios and the tests already written for them
The test strategy for the epic
The built code, read for branches and states the scenarios do not mention
Produces
Extended test suite in unit tests with the project; integration and e2e under tests/. Done when:
Adds tests for boundaries, state transitions, error and recovery paths, concurrency, and realistic interaction sequences where relevant
Does not duplicate Development's tests
Gaps as scenarios and questions in the feature pages in the knowledge base and the anchor ticket. Done when:
Every behaviour found that the requirement did not specify is a question on the ticket and a Draft scenario proposed on its feature page
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
From the test-writing set: What every step that writes or extends automated tests does: prove with the actual run, and keep every test deterministic and independent.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-46 Make every test deterministic and independent: inject or freeze time, seed or inject randomness, give each test its own state and clean it up, and replace external dependencies with a container, a fake, or a recorded response; never depend on test order, on state another test left, or on a sleep. A test that fails intermittently is a defect: quarantine it with a ticket the same day, never retry it into green or skip it without one (G-06).
For this step:
G-07 Write business-facing behaviour as Gherkin scenarios in the features folder before the change, and technical behaviour as executable tests alongside it.
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-19 Tag every Approved scenario on its feature page with the ticket that asked for it, and link the ticket to the page and the scenario ids.
G-21 Start from the scenarios pulled from the feature pages, then apply general testing strategies (boundaries, state transitions, error and recovery paths, concurrency, realistic user interaction sequences) to find what the requirement did not say. Record each gap as a question on the ticket and a Draft scenario proposed on its feature page, never in the feature file.
G-49 Give every feature a stable id (F-nnn) and every scenario one derived from it (F-nnn-nn), assigned on its feature page once and never renumbered or reused; tag or name every automated test with the ids of the scenarios it proves, so coverage is the set of scenario ids that at least one test names.
Read Development's tests first and say what they cover. Your job starts where theirs stops.
Test the seams. The boundaries between components, between tiers, and between the system and its dependencies are where the requirement was vaguest.
Every test you add runs alone and in any order with the same result. Control time, randomness, state, and dependencies; never lean on another test having run first (O-23).
A Draft scenario on the feature page is a real scenario awaiting an answer; it reaches the repository only when its owner approves it. Do not leave gaps as comments in test code, and never add them to a feature file (G-18).
Tenets T-07, T-12 | Opinions O-08, O-23
Build end-to-end tests /aa-qa-e2e-tests
Automate the scenarios that can only be proven through the whole system as the user sees it, and where a user interface exists, the visual regression suite that catches what functional tests cannot.
The scenarios assigned to the end-to-end tier by the strategy
The system and its dependencies, started in containers from the repository's definitions where the stack allows (O-12)
The project's end-to-end and visual testing tool categories
Produces
End-to-end test suite in tests/e2e. Done when:
Runs from the root test script with the e2e tier
Each test maps to a scenario by tag; flaky tests are quarantined with a ticket, not retried into green
Visual regression suite in tests/e2e. Done when:
Baselines are versioned and reviewed when they change
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
From the test-writing set: What every step that writes or extends automated tests does: prove with the actual run, and keep every test deterministic and independent.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-46 Make every test deterministic and independent: inject or freeze time, seed or inject randomness, give each test its own state and clean it up, and replace external dependencies with a container, a fake, or a recorded response; never depend on test order, on state another test left, or on a sleep. A test that fails intermittently is a defect: quarantine it with a ticket the same day, never retry it into green or skip it without one (G-06).
For this step:
G-21 Start from the scenarios pulled from the feature pages, then apply general testing strategies (boundaries, state transitions, error and recovery paths, concurrency, realistic user interaction sequences) to find what the requirement did not say. Record each gap as a question on the ticket and a Draft scenario proposed on its feature page, never in the feature file.
G-30 Run the end-to-end tier against the system and its dependencies started in containers from definitions committed to the repository, so it runs the same way on any machine and in the pipeline. Reach a shared environment only for a dependency that cannot be containerised, and record which tests depend on it.
G-49 Give every feature a stable id (F-nnn) and every scenario one derived from it (F-nnn-nn), assigned on its feature page once and never renumbered or reused; tag or name every automated test with the ids of the scenarios it proves, so coverage is the set of scenario ids that at least one test names.
Drive the system the way a user does, through its real entry points; do not reach into internals to make a test pass.
Own the test data. Every end-to-end test creates what it needs and cleans up; a test that depends on leftover state will lie eventually.
Own the environment too. Start it from the repository's container definitions and tear it down after; a test that needs a shared environment is marked and the reason recorded (O-12).
A flaky test is a defect in the test or the system. Quarantine it with a ticket the same day; never wrap it in a retry to hide it (G-06, O-23).
Tenets T-07 | Opinions O-07, O-12, O-23
Performance and load test /aa-qa-performance-test
Establish how the system behaves under expected and peak load against stated targets, record the baseline, and raise tickets where targets are missed.
Performance targets from the technical constraints and scenarios
A production-like environment and the project's load testing tool category
Produces
Performance test suite in tests/e2e or the location the project config names for performance tests. Done when:
Reproducible: environment, data volume, and load profile are recorded with the suite
Performance baseline report in the knowledge base, linked from the ticket. Done when:
Reports each target with the measured value, the method, and pass or fail
Every miss is a ticket with the measured gap
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
From the test-writing set: What every step that writes or extends automated tests does: prove with the actual run, and keep every test deterministic and independent.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-46 Make every test deterministic and independent: inject or freeze time, seed or inject randomness, give each test its own state and clean it up, and replace external dependencies with a container, a fake, or a recorded response; never depend on test order, on state another test left, or on a sleep. A test that fails intermittently is a defect: quarantine it with a ticket the same day, never retry it into green or skip it without one (G-06).
For this step:
G-30 Run the end-to-end tier against the system and its dependencies started in containers from definitions committed to the repository, so it runs the same way on any machine and in the pipeline. Reach a shared environment only for a dependency that cannot be containerised, and record which tests depend on it.
No target, no test. If the requirement has no number, get one from the ticket owner before running anything; "fast" is not a target.
Measure with a tool and report the distribution, not the average. The slowest 5 percent is what users complain about.
Record the environment with the result. A number without the machine, data volume, and load profile cannot be compared to anything later.
Tenets T-07 | Opinions O-23
Exploratory testing /aa-qa-explore
A time-boxed session using the system with a charter and a testing lens (boundaries, states, errors, interruptions, roles), recording every surprise as a defect, a question, or a new scenario.
Records what was tried, what surprised, and what was concluded
Every surprise is a ticket, a question, or a Draft scenario on its feature page
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-21 Start from the scenarios pulled from the feature pages, then apply general testing strategies (boundaries, state transitions, error and recovery paths, concurrency, realistic user interaction sequences) to find what the requirement did not say. Record each gap as a question on the ticket and a Draft scenario proposed on its feature page, never in the feature file.
G-23 State a time box for any open-ended investigation before starting it, stop when it is reached, and report what was found either way.
Follow the charter until the time box, then follow the most interesting surprise. Both halves matter.
Interrupt things. Cancel midway, lose the connection, double-submit, go back; the scenarios almost never say what should happen.
Tenets T-07
Documentation doc
Keeps what is written true. Documents each feature for the people who will use and maintain it, keeps the knowledge base aligned with the feature files and the code, and periodically audits the whole for drift.
Owns:
User-facing and developer-facing documentation for a feature
The knowledge base pages that back feature files, and their alignment (T-12)
Documentation health audits and the tickets they raise
Document a feature /aa-doc-document-feature
Write or update the user-facing and developer-facing documentation for a ticket, from its scenarios and its implementation, in the places the project keeps each kind.
The ticket, its feature pages and their scenarios, and the merged change
The project's documentation locations from the config or knowledge base
Produces
Feature documentation in the documents folder for developer docs; the knowledge base's Guides section, around the feature page, or the project's user documentation location for user docs. Done when:
A user can do what the scenarios describe by following the user documentation
A developer can find where the feature lives and how it is tested from the developer documentation
Linked from the ticket and the feature page, and restates no scenario the page holds
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-53 Put each knowledge base page under the project's own root, in the section its content belongs to (Overview, Requirements, Architecture, Operations, Releases, Guides, or the names the project config maps them to), name a requirement page after its feature and its feature id, and when a page is superseded mark it and link to what replaced it rather than deleting it.
Write from the scenarios, verify against the software. The scenarios say what should happen; run the feature to confirm the documentation is describing what does.
Document the unhappy path. Users read documentation when something went wrong.
Never duplicate a scenario in prose. The feature page holds it; link to the page and write the explanation around it, since two copies drift.
Tenets T-12, T-13 | Opinions O-16
Maintain documentation /aa-doc-maintain-docs
Audit the feature files, the documentation, and the knowledge base for drift from the feature pages and the code, fix what is wrong, and raise tickets for what needs an owner. Recurring; each run anchors on a maintenance ticket.
The project's feature pages and other pages under its knowledge root, the feature files, and the documents folder
Changes merged since the last audit
Produces
Up-to-date documentation in wherever it lives; changes on a branch linked to the ticket. Done when:
Every feature file was pulled from its feature page, is unedited, and is current with the page (T-12, R-46)
Every Approved scenario is linked to a ticket (G-19)
No documented behaviour contradicts a scenario or the running software
Documentation health report in the knowledge base. Done when:
Lists what was checked, what was fixed, and what is ticketed for someone else
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the repository-write set: What every step that changes files in the repository does: keep artifacts with the code, write Conventional Commit messages, one cohesive change per commit, stage and present rather than commit, and name the purpose of every change.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
For this step:
G-18 Change a requirement on its feature page in the knowledge base, under the ticket that asks for it, then pull the page into the repository. Never edit a feature file by hand; a change found while building is converted to the page format and proposed on the page for its owner to approve.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-53 Put each knowledge base page under the project's own root, in the section its content belongs to (Overview, Requirements, Architecture, Operations, Releases, Guides, or the names the project config maps them to), name a requirement page after its feature and its feature id, and when a page is superseded mark it and link to what replaced it rather than deleting it.
Start from the feature pages and walk outward. They are the truth; every feature file, page, and document is checked against them, never the reverse.
Delete confidently. Documentation for something that no longer exists is worse than none; remove it and say so in the report.
A contradiction between a document and a scenario is a conflict to surface, not something to quietly fix; a scenario changes only on its page, with its owner's approval (T-12).
Audit only what is this project's, the pages under its knowledge root and the tickets its filter selects; a problem in a shared space or another project's page is named for its owner, not changed (T-14).
Tenets T-12 | Opinions O-16
Release Management rel
Gets built, tested software into production deliberately and gets it back out if it must. Owns the version, the release notes, the go/no-go decision, the production deployment record, and rollback. Release Management never asks what to release; it asks whether it is ready.
Owns:
Versioning and the release notes generated from tickets and commits
The change record and go/no-go checklist for a release
Production deployment and its verification record
Rollback and its record
Prepare a release /aa-rel-prepare-release
Assemble a release: decide the version, generate release notes from the tickets and commits since the last release, write the change record, and run the go/no-go checklist. Produces everything needed to say "ready" or "not yet".
Merged changes and their tickets since the last release tag
Test results across all tiers, security test results, and UAT results
The project's versioning and release conventions
Produces
Version and release notes in source control as a tag and notes file; the ticket system as the release; the knowledge base. Done when:
Version follows the project's scheme and the bump is derived from the commit types since the last tag (O-14); the release names the artifact identity that was tested (O-24)
Every included ticket appears in the notes; nothing appears that is not included
Written for the audience the project names: users, operators, or both
Change record and go/no-go checklist in the release ticket. Done when:
Every checklist item has evidence linked or is marked not applicable with a reason
The decision and who made it are recorded
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-34 Derive the release from the history: the version bump from the commit types since the last tag (breaking change, feature, fix) and the release notes by grouping commits by type and ticket, then edit the notes for the reader. A commit that does not parse is a finding on the release ticket, not something to work around.
G-47 Build the release artifact once, from one commit, give it an immutable identity, and promote that same identity through every environment; supply environment configuration at deploy time from the committed templates (O-16), never by rebuilding. Record the identity on the release, roll back to a previous identity rather than a rebuilt tag, and verify in each environment that the running identity is the one deployed.
Generate the notes from the record, then edit for the reader. Group commits by type and ticket (O-14); tickets and commits say what changed, a person says what it means.
Never mark a checklist item done on someone's word. Link the test run, the approval, the scan.
A release with an unexplained change in it is not ready. Every commit since the last tag traces to a ticket or gets one.
Tenets T-06, T-07 | Opinions O-14, O-19, O-24
Release to production /aa-rel-release
Deploy a prepared release to production using the pipeline Operations provides, verify it did what the release notes say, and record the deployment. Stops and asks before the irreversible step.
The deployment pipeline and runbook from Operations
The verification checks defined in the release
Produces
Production deployment record in the release ticket and the knowledge base. Done when:
Records what was deployed, by its immutable artifact identity, when, by whom, with which pipeline run (O-24)
Deployment verification report in the release ticket. Done when:
Every verification check has a result; any failure triggers rollback or an incident, recorded
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-14 Never use a bypass flag on a hook, check, or protected branch. If a gate blocks, fix the cause or tell the user.
G-47 Build the release artifact once, from one commit, give it an immutable identity, and promote that same identity through every environment; supply environment configuration at deploy time from the committed templates (O-16), never by rebuilding. Record the identity on the release, roll back to a previous identity rather than a rebuilt tag, and verify in each environment that the running identity is the one deployed.
G-51 Move a ticket to a life-cycle state only in the step that produces its evidence, and write that evidence on the ticket as it moves: Refined when its scenarios are linked and the revision recorded, Planned when the plan is confirmed and sized, In progress when work starts on its branch, In review when its merge request is open, Accepted when the stakeholder confirms it, Done when it is released; use the ticket system's names for the states as the project config maps them.
G-53 Put each knowledge base page under the project's own root, in the section its content belongs to (Overview, Requirements, Architecture, Operations, Releases, Guides, or the names the project config maps them to), name a requirement page after its feature and its feature id, and when a page is superseded mark it and link to what replaced it rather than deleting it.
Ask before you deploy, every time, unless the user granted this deployment in advance. Production is the irreversible step (G-13).
Use the pipeline, not your hands. A deployment done outside the pipeline is unrecorded and unrepeatable.
Verify before you announce. The release is not done when the pipeline is green; it is done when the checks pass in production.
If verification fails, the default is rollback, not investigation in production.
Tenets T-06, T-07 | Opinions O-24
Roll back a release /aa-rel-rollback
Return production to the previous known-good release using the pipeline, verify it, record what was rolled back and why, and hand the cause to Support or Development.
The release to roll back and the previous known-good release
The rollback runbook from Operations
The incident or verification failure that triggered it
Produces
Rollback record in the release ticket and the incident, if any. Done when:
Records what was reverted to, when, by whom, and the trigger
Verification after rollback is recorded
A ticket exists for the cause
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-47 Build the release artifact once, from one commit, give it an immutable identity, and promote that same identity through every environment; supply environment configuration at deploy time from the committed templates (O-16), never by rebuilding. Record the identity on the release, roll back to a previous identity rather than a rebuilt tag, and verify in each environment that the running identity is the one deployed.
Roll back first, understand later. The goal is to restore service; the cause is a ticket.
Confirm the rollback target is actually known-good, not just previous. Check its verification record, and roll back to that artifact identity; never rebuild the previous tag (O-24).
Data changes may not roll back with code. Say so explicitly and involve Operations before proceeding.
Tenets T-06, T-07 | Opinions O-24
Operations ops
Provides and runs the environments the software lives in. Infrastructure as code, the pipeline that delivers to it, the observability that shows what it is doing, and the validation that production behaves as the release claimed.
Owns:
Infrastructure as code and deployment runbooks
The delivery pipeline and deployment strategy
Monitoring, dashboards, alerting, and the observability requirements on the code
Production validation after a release
Set up infrastructure /aa-ops-setup-infrastructure
Define the environments the system runs in as code, with runbooks for the operations that are not automated, meeting the constraints from architecture and the controls from security.
The architecture, technical constraints, and security requirements
The organisation's platform standards from the enterprise scope
The project's infrastructure tooling category
Produces
Infrastructure code in the source folder, as its own project, on a branch linked to the ticket. Done when:
Every environment is reproducible from the code with no manual steps beyond the runbook
A configuration template exists for every environment, with every key named and no secret values (O-16), holding only the settings that differ between environments (O-25)
Security controls from the threat model are implemented or ticketed
Deployment runbooks in the documents folder. Done when:
Every manual operation has a runbook with preconditions, steps, verification, and rollback
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
For this step:
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-38 Never commit a secret value. Commit a configuration template that names every key with a placeholder for each secret, and record in the development environment configuration where each secret comes from and how a fresh clone obtains it.
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
G-48 Split configuration by what varies: settings that differ between environments (endpoints, connection strings, resource names, credentials) go in an environment file or the platform's equivalent, one per environment with a committed template, supplied at deploy time; settings that are the same everywhere (timeouts, limits, behaviour) go in the application configuration committed once with the code. Never put a key in both; when adding a setting, ask which kind it is and put it in that one place, and if a functional setting must differ for one environment, record why in a decision record rather than copying the configuration.
Everything as code, reviewed and tested like code. An environment changed by hand is an environment nobody can rebuild (O-16).
Least privilege by default. Every credential, role, and network path is the narrowest that works, and widening one is a decision record.
Ask before creating anything that costs money or is hard to delete.
Set up the delivery pipeline /aa-ops-setup-pipeline
Build the pipeline that takes a merged change to production: build, every test tier, security checks, packaging, deployment per environment, and the deployment strategy that makes a release safe to ship and to roll back.
The root scripts (build, test, pack) and the infrastructure code
The release and deployment conventions
The project's pipeline tooling category
Produces
Deployment pipeline configuration in the repository, in the location the pipeline tool expects. Done when:
Calls the root scripts rather than duplicating their logic (O-06)
Runs every test tier and fails on any failure; no skipped stages without a recorded reason
Runs the root build with the lint switch as its lint stage (O-21)
Deploys to each environment the same artifact, built once and identified immutably; no deploy stage builds (O-24)
Every stage calls a script or command in the repository that runs locally with the same arguments (O-11)
Deployment strategy documentation in the documents folder. Done when:
States the strategy (for example staged, canary, blue-green) and how rollback works for it
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
For this step:
G-14 Never use a bypass flag on a hook, check, or protected branch. If a gate blocks, fix the cause or tell the user.
G-29 Put every pipeline step's logic in a root script or a command committed to the repository and call it from the pipeline with the same arguments; when a pipeline step fails, reproduce it locally with that same script before changing anything. A step that can only run in the pipeline is a defect: ticket it and move the logic out.
G-38 Never commit a secret value. Commit a configuration template that names every key with a placeholder for each secret, and record in the development environment configuration where each secret comes from and how a fresh clone obtains it.
G-47 Build the release artifact once, from one commit, give it an immutable identity, and promote that same identity through every environment; supply environment configuration at deploy time from the committed templates (O-16), never by rebuilding. Record the identity on the release, roll back to a previous identity rather than a rebuilt tag, and verify in each environment that the running identity is the one deployed.
G-48 Split configuration by what varies: settings that differ between environments (endpoints, connection strings, resource names, credentials) go in an environment file or the platform's equivalent, one per environment with a committed template, supplied at deploy time; settings that are the same everywhere (timeouts, limits, behaviour) go in the application configuration committed once with the code. Never put a key in both; when adding a setting, ask which kind it is and put it in that one place, and if a functional setting must differ for one environment, record why in a decision record rather than copying the configuration.
The pipeline calls the scripts; the scripts do the work. Logic in pipeline configuration cannot be run locally and will drift (O-11).
One artifact, promoted. Build once, give it an immutable identity, deploy that identity everywhere; never rebuild for a later environment (O-24).
A pipeline that can be bypassed is not a pipeline. Protect the branches it deploys from.
Make the running system visible: the dashboards, alerts, logs, and traces that show whether the scenarios are being met in production, and the requirements on the code to emit them.
Monitoring dashboards in the observability tool, linked from the knowledge base. Done when:
Show the outcome metrics from define-outcome and the health of each component
Alert configuration in as code in the repository where the tool allows; otherwise documented in the documents folder (O-16). Done when:
Every alert has a runbook, an owner, and a threshold with a reason
No alert fires that nobody acts on
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
From the code-change set: What every step that changes code, configuration, or infrastructure does, on top of repository-write: format changed files, prove with the build and tests, plan before a multi-step change, reference the ticket, commit everything needed to build and operate, let the tools decide style, change dependencies through the package manager, and never let a hand-edited feature file through.
G-01 Always format the code for the changed files before committing, but do not format files that were not changed.
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-08 Before any multi-step change, write the plan and get it confirmed; one concern per commit and one ticket per branch is G-39.
G-09 Reference the anchor ticket in the branch name and every commit message.
G-11 Every artifact that belongs with the code goes into the same change set as the code, staged for the commit the user makes (G-40). Nothing that matters is left only on a local disk or in a conversation.
G-33 Write every commit message in Conventional Commits form: a type from the project's list, an optional scope, an imperative subject, a body that says why, and a footer carrying the ticket reference and any breaking change. One concern per commit (G-39); if you cannot name the type, split the commit.
G-37 Commit everything needed to build, deploy, and operate the software with the change that needs it: configuration templates, migrations, scripts, pipeline, infrastructure, container, and alert definitions, runbooks, and the development environment configuration. If a fresh clone plus the documented secrets could not build, deploy, and run the system after your change, something is missing from the repository; find it and commit it.
G-39 Make each commit one understandable change: one concern per commit, one ticket per branch, a subject that says what and a body that says why, small enough to review in one sitting. If the subject needs "and" or the diff needs a tour, split it.
G-40 Never commit unless the user asked for that commit. Stage the change, write the message, present the staged diff summary and the message, and stop; a request to implement, fix, finish, or run a step is not a request to commit, and the commit is made under the user's identity with no agent attribution.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
G-44 Let the tools decide style: conventions live in the repository as formatter configuration and a static analyser rule set, the formatter runs on changed files and the analyser runs from the root build before a change is presented, and every finding is fixed or suppressed with a reason beside it. Never argue style in review; where a language has no known linter, record that once in the development environment configuration and expect the health warning.
G-45 Change dependencies only through the ecosystem's package manager: add, update, and remove with its commands so it resolves conflicts, surfaces warnings, and updates transitive dependencies and the lock file together, and stage the manifest and lock file changes as their own commit (G-39). Never edit a version in a manifest or lock file by hand; if the tool refuses, record the refusal on the ticket and resolve it, never bypass it.
G-56 Before a change is committed and before it is merged, check the feature files: every one carries its provenance header, matches its checksum, and is generated by a page. Refuse a change that fails, and say to change the page and pull it instead.
For this step:
Alert on what users feel, not on what machines do. Latency and error rate at the edge before CPU in the middle.
Every alert has a runbook or it is noise. Write the runbook before enabling the alert.
Observability is a requirement on the code. If a scenario cannot be observed in production, raise a ticket for the signal.
Tenets T-07 | Opinions O-16
Validate production /aa-ops-validate-production
After a release, confirm from production evidence that the system is doing what the release claimed: run the production validation checks, compare metrics to the baseline, and report.
The release, its verification checks, and its notes
Dashboards, metrics, and logs since the release
The performance baseline
Produces
Production validation results in the release ticket. Done when:
Every check has a result with evidence
The identity of the running artifact matches the one the release named (O-24)
Production metrics report in the knowledge base. Done when:
Compares key metrics before and after, computed with a tool, with any regression ticketed
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-47 Build the release artifact once, from one commit, give it an immutable identity, and promote that same identity through every environment; supply environment configuration at deploy time from the committed templates (O-16), never by rebuilding. Record the identity on the release, roll back to a previous identity rather than a rebuilt tag, and verify in each environment that the running identity is the one deployed.
Compare, do not glance. Compute before-and-after for each metric over a stated window; a dashboard that "looks fine" is not evidence.
Validation is read-only. Never change production to make a check pass; a failing check is an incident or a rollback.
Tenets T-07, T-10 | Opinions O-24
Support sup
Is the front door for what goes wrong in production. Triages incoming incidents and requests into tickets with the right priority, coordinates response until the impact is contained, and runs the post-incident review that turns an incident into prevention.
Owns:
Incident and request intake, triage, and prioritisation
Incident response coordination, timeline, and mitigation until resolved
Post-incident review and the prevention tickets it raises
User-facing follow-up
Triage /aa-sup-triage
Take an incoming incident, defect report, or request and turn it into a ticket with the right type, severity, priority, and owner, or link it to the existing ticket it duplicates.
The incoming report from whatever channel the project uses
Existing open tickets and known issues
The project's severity and priority definitions
Produces
Triaged ticket in the ticket system. Done when:
Has a type, severity, priority, and owner, each per the project's definitions
Has enough to act on: environment, steps, expected, actual, impact
Duplicates are linked, not created
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-16 State assumptions and unverified claims explicitly, and put unresolved questions on the anchor ticket.
G-52 Create every ticket as one of the five kinds, in the ticket system's name for it from the project config: an epic for an outcome, a story for one behaviour a user can observe with its scenarios, a task for a buildable piece of a story's plan, a bug for behaviour that contradicts a scenario, a spike for a time-boxed question; link each to its parent (task to story, story to epic).
Severity is impact, priority is order. Do not let a loud reporter set either.
Ask for what is missing once, precisely. A ticket that cannot be reproduced from its content goes back with the exact questions.
Check for duplicates before creating. Search by symptom, not by the reporter's title.
Tenets T-04, T-13
Respond to an incident /aa-sup-respond-incident
Coordinate an active incident: keep a timeline, contain the impact, pull in Operations, Development, or Release Management as needed, communicate status, and close the incident when service is restored.
The incident ticket with severity and current impact
Dashboards and alerts from observability
Runbooks and the rollback option
Produces
Incident timeline in the incident ticket. Done when:
Every action and observation is timestamped as it happens
Communications sent are recorded with their audience
Mitigation in the incident ticket, with links to any rollback or change. Done when:
Service is restored, verified with evidence, and the ticket says how
A post-incident review is scheduled
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-04 Before marking a step done, run the project's build and tests and quote their actual output. "It should work" is not evidence.
G-13 Stop and ask before any irreversible action (deploy, delete, external message, merge to a protected branch) unless the user granted it in advance.
G-42 Before making a change, name what it is for: the ticket, the scenario it satisfies, or the decision record or page that explains it, and put that reference where the change lives: the branch, the commit footer, the merge request, and the artifact. A change that cannot name its purpose is a ticket to create first or work not to do; in review, a hunk that traces to nothing is a finding.
Contain first, diagnose second. Rollback, feature flag, or scale before root cause.
Write the timeline as you go. A timeline reconstructed afterwards is fiction with timestamps.
Say what you know and what you do not, at a stated cadence. Silence during an incident is the worst status update.
Tenets T-06, T-07 | Opinions O-19
Post-incident review /aa-sup-postmortem
After an incident is closed, review what happened using the timeline and the evidence, find the contributing causes without blame, and raise the tickets that will prevent recurrence or shorten the next response.
Post-incident review in the knowledge base, linked from the incident. Done when:
States impact, detection time, response time, and time to restore, computed from the timeline
Lists contributing causes; names systems and decisions, not people
Prevention tickets in the ticket system. Done when:
Every action item is a ticket with an owner; the review links them
Guidance the agent follows
From the every-step set: What every step does regardless of discipline: compute rather than estimate, read before writing, never suppress a failure, report exactly, write for a reader with no context, and touch only what is this project's in systems shared with others.
G-02 Perform any arithmetic, date calculation, counting, or unit conversion by executing code or a tool, and report the executed result, never an estimate.
G-03 Read the current contents of a file, ticket, or document immediately before modifying it; never edit from memory of an earlier read.
G-06 Never suppress a failing test, warning, or error to make a step pass. Fix the cause, or record the unresolved problem on the anchor ticket.
G-15 Report outcomes exactly: failures with their output, skipped steps as skipped, partial work as partial.
G-24 Write every artifact for a reader with no context: someone who was not in this session and may never have seen the project. If it needs the conversation to make sense, it is not finished (T-13).
G-55 In a ticket system or knowledge base shared with others (T-14), read, count, create, and change only what the project config selects as this project's: its tickets through the configured ticket filter, and its pages under the configured knowledge root. Never change a shared workflow, board, space structure, or another project's ticket or page without its owner's consent; name the change for the owner instead.
From the anchored-step set: What every step that anchors on a ticket does: anchor first and pull the feature pages it links to, end by updating the ticket, put artifacts where the workflow says, link both ways, stay inside the one configured ticket project.
G-12 End every step by updating the anchor ticket with what was done, what was produced, and what remains.
G-22 Anchor first. Before doing anything, read the anchor ticket, its linked scenarios, and its knowledge base page. If there is no ticket and the step needs one, create it or ask; never work from the conversation alone.
G-25 Produce each artifact in the location the workflow names for it, with the name it gives. Never invent a new location or a variant name; if the named location is wrong for this project, change the project config, not the artifact (T-08).
G-26 Link in both directions. Every artifact links to its anchor ticket, and the ticket links back to the artifact; a feature links to its page and the page to the feature.
G-27 Create and anchor tickets only in the repository's one configured ticket project. If the work touches a ticket in another project, create or use a ticket in this project and link the two; never anchor a step on a ticket outside the configured project.
G-54 Begin every step that anchors on a ticket by pulling the feature pages the ticket links to: their Approved scenarios into the features folder, each file with its provenance header, and the page versions recorded on the ticket. Work only from freshly pulled feature files; a feature file that differs from its page is not the requirement.
For this step:
G-41 Write every significant decision, technical, product, or process, as a decision record the moment it is made: one screen, numbered next in the repository's sequence, dated, with context, options considered, decision, and consequences, linked from the anchor ticket. Never edit an accepted record; supersede it with a new one that links back.
Compute the times from the timeline with a tool; do not estimate them.
Ask "what made this reasonable at the time" for every decision in the timeline. Blame finds a person; this finds a cause.
Prefer one action that removes the cause over five that add checks around it.
