chore(sdd): bootstrap SDD governance artifacts

[jeffersontuc]

Summary

This PR introduces the SDD governance artifacts required by the Engineering Golden Path:

• Initialized spec-kit and removed the IDE-specific generated outputs (.cursor/) to keep the repository neutral; engineers can regenerate them locally with uvx --from git+https://github.com/github/spec-kit.git specify init . --here --integration <their-tool>.
• out/spec-repo/checkout-graphql/constitution.md — non-negotiable principles and standards. Because this repository is public, the constitution is routed to the central spec-repo and is not committed here (see Public-Repo Routing below).
• AGENTS.md — agent-facing operational guidance (105 lines).

It was generated automatically by the sdd-bootstrap skill, against a repository in green-field state. Treat it as a starting point, not a finished document — your team owns the final content. The PR is intentionally opened as a draft; mark it ready-for-review when the team is satisfied.

Reference: Engineering Golden Path of the SDLC in the GenAI Era.

Repository State

green-field — no .specify/ directory was present; spec-kit was initialized as part of this PR.

Detected Family

vtex-io-app

Evidence:

• manifest.json declares "vendor": "vtex" and a builders block (graphql: 1.x, node: 6.x).
• Resolvers live under node/resolvers/ (one file per top-level GraphQL type); directives are declared in graphql/directives.graphql with implementations in node/directives/.
• Service runtime is declared in node/service.json (stack: nodejs).
• App dependencies pinned in manifest.json.dependencies: vtex.country-data-settings, vtex.graphql-server, vtex.messages.

If the detected family is wrong, close this PR and re-run the skill manually with the correct family override; do not edit this PR's files to retrofit a different family.

What Was Generated

File / Directory	Status
.specify/ scaffolding (scripts/, templates/, workflows/, integrations/, init-options.json, integration.json)	Newly created by uvx specify init . --here --integration cursor-agent --force --no-git.
.specify/memory/constitution.md	Not present here. Public-repo routing: the rendered constitution lives at out/spec-repo/checkout-graphql/constitution.md in the bootstrap working tree and is mirrored to the central spec-repo by the rollout pipeline.
AGENTS.md	Newly authored at the repository root (105 lines).

Constitution version: 1.0.0 (first ratification of the constitution for this repository).

Note on IDE-specific files: spec-kit also generates slash commands and skill files under .cursor/, .claude/, or .github/prompts/ depending on the --integration flag. This skill removes those after initialization to keep the repository IDE-neutral. If you want them locally, run:

uvx --from git+https://github.com/github/spec-kit.git specify init . --here --integration <your-tool>

This regenerates only the IDE-specific commands; it does not touch .specify/.

Files Preserved (not modified by this PR)

• README.md, CHANGELOG.md, .github/CODEOWNERS, .github/workflows/ci.yml, .github/workflows/test-node.yml, lint.sh, sonar-project.properties, manifest.json, package.json, yarn.lock, node/**, graphql/**, docs/**, .gitignore — all untouched.
• No CI workflow, Dockerfile, Makefile, or vendored dependency was modified.

Review Checklist (the team must complete before merge)

• The detected family (vtex-io-app) is correct.
• The detected state (green-field) matches what you expected — there was no prior .specify/ directory in main.
• Every Core Principle in the constitution is one the team actually wants to enforce; remove or rewrite any that do not match reality.
• The "Stack-Specific Standards" section reflects current versions and tooling (TypeScript 3.9.7 in node/, Node 12.x in CI, yarn, vtex-test-tools, eslint-config-vtex).
• The "Architectural Boundaries" section in AGENTS.md matches the real layering of this repository.
• The "Operational Constraints" commands (yarn lint, cd node && yarn test:coverage, cd node && yarn tsc --noEmit, vtex link/publish/deploy) run successfully on a fresh checkout.
• Both <!-- TODO(team) --> markers in the constitution have been resolved or intentionally accepted (see list below).
• AGENTS.md is under 200 lines (currently 105) and free of aspirational rules (only enforced ones).
• The Safety Guardrails list in AGENTS.md has been reviewed for completeness against this repo's risk profile.
• The constitution lives in the spec-repo and the CODEOWNERS group @vtex-apps/checkout-ui is the right approver for amendments.

Open <!-- TODO(team) --> items (in the constitution)

1. Coverage floor (Principle IV): set a numeric coverage threshold. Coverage is currently collected via yarn test:coverage and reported to SonarQube (sonar-project.properties), but no threshold is enforced in CI.
2. Development account / workspace convention (Operational Constraints, Link to a workspace): document the canonical vtex login <ACCOUNT> / vtex use <WORKSPACE> values if the team uses a shared development workspace.

Public-Repo Routing

This repository's gh repo view reports visibility: PUBLIC. Per the Golden Path, constitutions for public repositories live in the centralized spec-repo, not alongside the source.

• The rendered constitution was written to out/spec-repo/checkout-graphql/constitution.md in the bootstrap working tree.
• A payload file (SPEC_REPO_PAYLOAD.json) was emitted at the working-tree root for the rollout pipeline to pick up:

  {
    "source_repo": "vtex-apps/checkout-graphql",
    "target_path": "out/spec-repo/checkout-graphql/constitution.md",
    "default_branch": "main",
    "family": "vtex-io-app"
  }

• Neither out/spec-repo/** nor SPEC_REPO_PAYLOAD.json is staged in this PR — they are intentionally local to the bootstrap working directory.
• AGENTS.md (this file) points reviewers to the spec-repo location in its "Constitution" section.

Out of Scope

• This PR does not install skill.md files; skills are distributed centrally via vtex/vtex-agent-skills.
• This PR does not modify CI workflows, Dockerfile, Makefile, or vendored dependencies. If any of those need updating to match the new constitution, open a follow-up PR. Note: .github/workflows/ci.yml and test-node.yml currently target master while the default branch is main — that's pre-existing repo state and outside the skill's allowlist.
• This PR does not amend an already-populated constitution.md. Re-running the skill after this PR merges will produce an audit Issue instead of another PR.

How to Re-run

/sdd-bootstrap

Re-running on a repository where this PR has already been merged (and the constitution has propagated to the spec-repo) produces an audit Issue rather than another PR; the skill never silently overwrites a populated constitution.

Made with Cursor

[vtex-io-ci-cd]

Hi! I'm VTEX IO CI/CD Bot and I'll be helping you to publish your app! 🤖

Please select which version do you want to release:

• Patch (backwards-compatible bug fixes)

• Minor (backwards-compatible functionality)

• Major (incompatible API changes)

And then you just need to merge your PR when you are ready! There is no need to create a release commit/tag.

• No thanks, I would rather do it manually 😞

[vtex-io-docs-bot]

Beep boop 🤖

I noticed you didn't make any changes at the docs/ folder

• There's nothing new to document 🤔
• I'll do it later 😞

In order to keep track, I'll create an issue if you decide now is not a good time

• I just updated 🎉🎉

[fdaciuk]

A few issues to address before this can be merged.

[fdaciuk]

The Golden Path standard requires both Expected skills and Expected MCPs sections in AGENTS.md — mandatory for both minimal and detailed modes. Add a section listing the internal VTEX skills the team expects agents to use (e.g. specification, implementing) and another for the relevant MCPs (e.g. GitHub MCP, Atlassian MCP).

[fdaciuk]

Typo: "at all cost" → "at all costs".

[fdaciuk]

integration still points to cursor-agent, but the .cursor/ files were removed in this PR. Running specify init locally will regenerate them. Update this to the integration the team actually uses, or document the expected behavior.

[fdaciuk]

The Golden Path how-to requires symlinking .claude/skills → .agents/skills, .claude/commands → .agents/commands, and .claude/rules → .agents/rules so Claude Code picks up the installed skills. Without these, /specification and /implementing won't be available in Claude Code without manual per-developer setup. Either commit the symlinks or add a setup step to the README/AGENTS.md.