| name | implementing |
| description | Non-interactive sandbox implementation from an approved spec to a PR. Use when the user mentions "implement", "implement spec", "implement specs/<feature>.md", sandbox implementation, or autonomous implementation from a specification. |
| license | MIT |
| metadata | {"author":"VTEX","version":"1.2.0"} |
Implementing — Spec to Code
Implement a feature autonomously from an approved specs/<feature-name>.md.
Execution model
This skill assumes a sandboxed, asynchronous run: no human interaction during execution (no questions, confirmations, or waiting for replies).
| |
|---|
| Input | specs/<feature-name>.md (must be Approved — see Phase 1) |
| Success output | Pull Request on feat/<feature-name>, spec status → Done |
| Blocked output | Agent ends without a completed feature PR; a GitHub issue documents why implementation could not finish |
Pipeline (end-to-end): the specification skill produces the spec; this skill consumes it. There is no intermediate planning artifact or skill — you plan, decompose work, and sequence tasks internally. The spec is the single handoff contract.
Operating loop: pick a user story → implement with tests → verify against acceptance criteria → commit → repeat until every story is done. Evidence over claims: nothing is "done" until tests and checks prove it.
Constraints
What you CAN do:
- Create and modify source code, tests, and configuration files required by the spec
- Install dependencies explicitly mentioned in the Technical Contract or required by the chosen approach
- Create branches, commit, and open PRs
- Open a GitHub issue (or equivalent) when implementation is impossible to complete after tie-breakers and reasonable effort — see Non-interactive execution
What you CANNOT do:
- Implement features, endpoints, or behaviors not described in the spec
- Change the spec file itself — if the spec is wrong, contradictory, or blocking, follow Non-interactive execution (assumptions in PR, or issue + terminate)
- Skip writing tests for a user story that has acceptance criteria
- Merge or push to the main branch without explicit user consent (from platform policy outside this run)
The goal is simple: make every acceptance criterion pass. The spec is the single source of truth. If the spec says it, implement it. If the spec doesn't say it, don't.
Workflow
Phase 1: Load and validate
- Read the full
specs/<feature-name>.md
- Check that the status is
Approved. If it is not Approved (e.g. Draft): end the run immediately. Do not open an implementation PR. Emit a structured report in sandbox logs/output (reason, current status, path to the spec file) so the orchestrator can mark the job failed.
- Extract from the spec:
- User Stories + Acceptance Criteria → the work units
- Key Scenarios → the test cases
- Arch Decisions → the technical approach and constraints
- Technical Contract → interfaces, models, and boundaries to implement exactly
- If the spec references repositories you don't have context on, use the GitHub tool to fetch their structure, README, and dependencies
Internal planning: derive order of work, file touch list, and test strategy from the spec and repo. No separate plan-approval step.
Phase 2: Codebase reconnaissance
Before writing any code, understand the existing codebase:
- Project structure, conventions, and patterns already in use
- Existing tests: framework, naming conventions, where they live
- Dependency management: what's already installed, what's available
- CI/CD: how tests are run, linting rules, build steps
Adapt your implementation to match existing patterns. Don't introduce new conventions unless the spec explicitly calls for it.
Phase 3: Implementation loop
Work through user stories one at a time. For each story:
LOOP per user story:
1. Write failing tests derived from the acceptance criteria and key scenarios
2. Run the tests — confirm they fail for the right reason
3. Implement the minimal code to make the tests pass
4. Run the tests — confirm they pass
5. Refactor if needed (tests must still pass after)
6. Commit with a descriptive message
7. Move to the next story
Rules:
- Follow the architecture described in Arch Decisions — don't contradict accepted decisions
- Implement interfaces and models exactly as defined in the Technical Contract
- One commit per user story (or per logical unit if a story is large)
- Commit messages follow the repo's existing convention; if none exists, use:
feat: <what was implemented>
- If a test fails after implementation and you cannot fix it after reasonable attempts (e.g. 3+ focused tries), treat this as blocking → Non-interactive execution (issue + terminate). Do not force a green build by gutting tests or the spec.
If something goes wrong:
- Implementation breaks existing tests → fix the regression before moving on; if the fix is not achievable without violating the spec or breaks invariants, treat as blocking → issue + terminate
- Ambiguity in acceptance criteria → apply tie-break order: Key Scenarios → Arch Decisions → Technical Contract → repository conventions. If ambiguity is resolved, document Assumptions in the PR body (dedicated section). If still unresolvable (no coherent reading), treat as blocking → issue + terminate
- A dependency is missing → install it if possible and note it in the PR summary; if it cannot be installed in the sandbox, treat as blocking → issue + terminate
- The spec contradicts itself in a way tie-breakers cannot reconcile → blocking → issue + terminate; do not guess
Phase 4: Verification
After all user stories are implemented:
- Run the full test suite — everything must pass
- Walk through the Key Scenarios table and confirm each scenario is covered by a test
- Check that no files were modified outside the scope of the spec
- Review your own changes: look for leftover debug code, TODOs, or unused imports
Phase 5: Deliver (success path)
- Update the spec status from
Approved to Done
- Open a Pull Request:
- Branch:
feat/<feature-name>
- Title:
feat: <feature-name>
- Body: use sections (not a live chat summary):
- Summary — what was implemented, per user story
- Tests — what was added or changed
- Assumptions — explicit assumptions from tie-breakers (omit section if none)
- Deviations — any deviation from the spec with justification (omit if none)
- Follow-ups — risks or optional next steps (omit if none)
- Spec — link to
specs/<feature-name>.md
- Reference the spec PR if it exists
Non-interactive execution
There is no human in the loop during the run: do not ask questions or wait for answers.
Success: proof lives in the PR description and passing tests (and CI, if applicable).
Blocked — impossible to complete the spec:
- Stop — do not open a PR that claims the feature is done.
- Open a GitHub issue with at minimum:
- Title pattern:
implementing blocked: <feature-name>
- Link to
specs/<feature-name>.md
- What was attempted (stories, commits, branches if any)
- Objective reason for the block (contradiction, missing dependency, irresolvable ambiguity, tests/CI that cannot be satisfied, etc.)
- Evidence: relevant spec excerpts, error output, failing test names
- End the agent run. Sandbox logs should reflect failure for the orchestrator.
Optional: push a WIP branch only if the orchestrator requires a trace — the issue is the primary failure artifact.
Important
- The spec is law — don't add features, don't skip requirements
- Tests are not optional — every acceptance criterion must have a corresponding test
- Match existing codebase patterns — don't impose new conventions
- Keep commits atomic — one story, one commit
- Never silently work around a broken spec — resolve with documented assumptions in the PR, or file an issue and stop