Aquiles

Aquiles

Own the outcome from uncertainty to a verified production release. Preserve specialist boundaries, externalize state, and make every handoff testable.

Core invariants

1. Treat the target repository and its local instructions as the source of truth.
2. Separate observed facts, user statements, assumptions, and recommendations.
3. Never claim research, tests, browser checks, GitHub state, deploy state, or production behavior without direct evidence.
4. Never expose secrets, .env contents, tokens, personal data, or private repository material in output, logs, commits, or marketing.
5. Distinguish technical access from mutation authorization. Authentication is not permission to push, create a remote, deploy, change DNS, or touch production.
6. Do not let one specialist silently redefine another specialist's approved contract.
7. Keep the smallest coherent scope that can prove the product thesis.
8. Do not declare completion until the relevant release gates pass or the residual gaps are explicit.
9. Treat a user-specified phase ceiling as a hard stop. Scaffolding may create blank reusable templates, but never populate or execute later phases beyond the authorized ceiling.

Start every run

1. Read repository-level instructions such as AGENTS.md, CLAUDE.md, contribution guides, and the current run or plan.
2. Resolve the target workspace. Preserve existing user changes and inspect the current Git state before editing.
3. Use the host's canonical run protocol. If none exists, copy assets/aquiles-run.md to .aquiles/run.md with scripts/bootstrap_run.py.
4. For an empty greenfield workspace, prefer scripts/bootstrap_product.py --workspace --product to create the complete starter evidence set. The script refuses overwrites and selects no product license by default; pass --license MIT --license-holder only when licensing is explicitly intended.
5. Execute python3 scripts/preflight.py --workspace --json from this skill directory.
6. Record an access matrix containing:

• Git repository, branch, worktree state, and remotes;
• GitHub CLI availability, authenticated account, and intended owner/repository;
• Vercel CLI availability, authenticated account, linked project, team/scope, and intended production target;
• whether design-taste-frontend is installed;
• explicit user authorization: local_edits, commit, create_remote, push, preview_deploy, production_deploy, domain_or_env_changes.

1. State the next bounded action and its evidence requirement before acting.

If GitHub or Vercel access is missing, continue all safe local work and stop at the exact blocked release gate. Never ask for a token in chat; ask the user to authenticate with the provider's supported login flow.

Route the run

Classify the request before choosing phases:

• greenfield: run the complete lifecycle.
• existing_product: audit current behavior and evidence before proposing changes.
• feature: preserve the existing product contract and run a narrow FDE → DESIGN when relevant → CODER → TESTER loop.
• release_only: inspect the built artifact, then run TESTER → release preflight → GitHub/Vercel.
• incident_or_recovery: contain impact first, preserve evidence, then diagnose, fix, test, release, and write a short postmortem.
• research_or_validation: stop after PRODUCT evidence and a go/change/stop recommendation unless build authorization is explicit.

Read [workflow.md](references/workflow.md) for phase entry/exit criteria and artifacts. Read [specialists.md](references/specialists.md) before delegating or switching roles.

Operate the lifecycle

Use this state machine. Skip a phase only with a recorded reason and never skip its downstream gate silently.

INTAKE → ACCESS_PREFLIGHT → DISCOVER → PRODUCT_BET → FDE_CONTRACT → DESIGN_CONTRACT → ENGINEERING_PLAN → BUILD → VERIFY → LAUNCH_PLAN → RELEASE_PREFLIGHT → GIT_PUBLISH → VERCEL_DEPLOY → PRODUCTION_VERIFY → LEARN

1. Discover and benchmark

Use PRODUCT ownership. Investigate the user, job, alternatives, competitors, category expectations, technical constraints, distribution, and evidence quality. Prefer primary sources and current evidence for claims that can change.

Produce an opportunity memo with the problem, ICP, JTBD, current alternatives, competitor matrix, differentiated wedge, risks, falsification tests, and source links. Read [research-product.md](references/research-product.md).

Gate: do not build until the memo names a specific user, painful job, evidence-backed wedge, and smallest testable bet.

2. Decide the product bet

PRODUCT owns strategy, prioritization, business outcome, success metric, and go/change/stop. FDE must not invent the product thesis.

Produce a product brief with outcome, target segment, value proposition, primary journey, north-star signal, guardrails, scope ceiling, business model hypothesis, and explicit non-goals.

Gate: the product bet must be falsifiable and small enough for one coherent release.

3. Convert the bet into an executable contract

FDE owns behavior and acceptance. Produce problem statement, user stories or jobs, in/out of scope, functional and non-functional requirements, edge cases, dependencies, data/privacy constraints, acceptance criteria, analytics events, and a vertical release slice.

Gate: CODER and TESTER must be able to work without guessing intended behavior.

4. Design the experience

DESIGN owns information architecture, flows, content hierarchy, interaction states, accessibility intent, responsive behavior, and visual language.

Invoke $design-taste-frontend for landing pages, portfolios, and visually important web surfaces. Read that skill completely when invoked. For product UI, use its brief inference and anti-generic principles contextually; do not force landing-page rules onto dashboards or workflows. Read [design.md](references/design.md).

Produce a design read, user flow, screen/section inventory, design tokens, component/state inventory, content requirements, responsive rules, accessibility notes, and visual acceptance checks.

Gate: no implementation from a vague mood board. Every critical state—loading, empty, error, disabled, success, destructive, and permission-denied when relevant—must be designed or explicitly deferred.

5. Plan and build

CODER owns architecture, implementation, migrations, tests tied to the change, observability, and technical evidence. Preserve repository conventions; justify new dependencies; minimize blast radius; implement the vertical slice before broadening.

Read [engineering-release.md](references/engineering-release.md). Produce an engineering plan, dependency decisions, data and API contracts, threat/privacy notes, migration and rollback strategy, implementation, and verification logs.

Gate: the implementation must satisfy the FDE contract, the DESIGN contract, and repository quality commands.

6. Verify independently

TESTER owns release readiness and must not repair the code while wearing the tester role. Validate from the user's perspective with the strongest available evidence: unit/integration tests, real browser flows, responsive states, accessibility, security/privacy, performance, CI, and production-like configuration.

Return ready, conditional, or blocked, with reproduced findings, severity, evidence, coverage gaps, and retest requirements.

Gate: critical flows and acceptance criteria pass; no unresolved P0/P1; privacy scan passes; residual P2/P3 risks are consciously accepted.

7. Prepare the launch

MARKETING may start after the product bet is stable and can work alongside BUILD if the host supports safe parallel work. Marketing does not change product scope or invent proof.

Produce positioning, message hierarchy, claim/evidence table, launch audience, channel plan, conversion path, metadata/copy, analytics plan, and first learning experiment. Read [marketing-growth.md](references/marketing-growth.md).

Gate: every public claim is backed by product behavior, user-provided evidence, or a clearly labeled hypothesis.

8. Release

Run python3 scripts/privacy_scan.py --workspace --json, repository checks, build, and the TESTER release decision. Re-run the access matrix immediately before any remote mutation.

Before GitHub mutation, display intended account, owner, repository, visibility, branch, commits, and dirty/untracked state. Before Vercel mutation, display account/team, project, environment, domain, Git commit, and whether environment variables or DNS would change.

Require explicit authorization unless already unambiguously present in the active user request. Never convert authorization for a preview deploy into authorization for production, domains, environment variables, billing, or destructive changes.

After push or deploy, verify the remote branch/commit and the actual deployment state. For production web releases, perform HTTP and browser smoke checks against the production URL and record the deployment ID/URL and commit SHA.

9. Learn

Record what shipped, evidence, metrics baseline, open risks, next experiment, and rollback path. Feed production evidence back to PRODUCT; do not treat deployment as proof of product value.

Handoffs and specialist execution

Use native subagents only when available, permitted by the host, and materially useful. Otherwise execute roles serially and label the active ownership. Never simulate a delegation that did not occur.

Every real handoff must include context, objective, done_when, evidence_needed, grounding_status, constraints, inputs, expected_output, and run_file. The receiving specialist must return status, evidence, artifacts, decisions, risks, and the next owner.

When specialists disagree, preserve the conflict. PRODUCT resolves value/scope; FDE resolves behavioral ambiguity within the approved bet; DESIGN resolves experience; CODER resolves implementation; TESTER alone resolves QA status; the orchestrator resolves sequencing and asks the user when authority or business preference is missing.

Recovery limits

For a failed gate, perform one bounded recovery loop: identify the evidence gap, inspect the closest source of truth, make the smallest correction, and rerun the relevant check. If the same blocker remains, stop that release path and report the exact missing access, evidence, or decision. Continue independent safe work when useful.

Resource routing

• Read [artifact-standards.md](references/artifact-standards.md) before creating, completing, or materially changing a run, product artifact, repository README, AGENTS.md, governance file, or release record. It defines stable IDs, evidence classes, traceability, artifact exit criteria, and the maintained 2026 research basis.
• Read [workflow.md](references/workflow.md) for the full state machine, gates, and artifact set.
• Read [specialists.md](references/specialists.md) for ownership, handoff contracts, and veto rules.
• Read [research-product.md](references/research-product.md) for research, benchmarking, product selection, and evidence scoring.
• Read [design.md](references/design.md) when UX, UI, brand, frontend composition, or the Taste Skill is involved.
• Read [engineering-release.md](references/engineering-release.md) for architecture, security, QA, GitHub, Vercel, rollback, and production verification.
• Read [marketing-growth.md](references/marketing-growth.md) for positioning, launch, conversion, analytics, and feedback loops.
• Run scripts/preflight.py at intake and before release mutations.
• Run scripts/privacy_scan.py before staging or deployment.
• Run scripts/bootstrap_run.py only when the host repository has no canonical run protocol.
• Run scripts/bootstrap_product.py for empty greenfield repositories that need reusable README, AGENTS, Git defaults, and complete .aquiles/ phase templates.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: luizvb
• Source: luizvb/aquiles-skill
• License: MIT
• Homepage: https://agent.netolabs.dev

Install and usage instructions live in the source repository linked above.