Skip to content

AGENTS.md

Latest commit

 

History

History
111 lines (80 loc) · 5.9 KB

AGENTS.md

File metadata and controls

111 lines (80 loc) · 5.9 KB
Raw

Project

Node 22 + Astro 5 (output: 'static') — sitio personal one-pager bilingüe EN/ES de Sebastián Rojas, migración 1:1 desde mockup estático; deploy a GitHub Pages (repo Sreddx/Rojas-web, base '/Rojas-web/')

Bootstrapped by agent-prep. Edit only via an agent-prep re-run.

Stack

  • Runtime: Node 22 (v22.22.2)
  • Language: TypeScript (strict) for src/data/; .astro components; vanilla JS ported
  • Framework: Astro 5.x, output: 'static' (no React/Vue/Svelte/Tailwind)
  • Package manager: npm (10.x)
  • ORM / DB: none (typed content in src/data/*.ts)
  • Test runner: Vitest (unit: data/i18n) + Playwright CLI (e2e smoke)
  • Lint / format: astro check (@astrojs/check)

Domain Map (generated)

  • frontend_paths: src/pages/, src/layouts/, src/components/, src/styles/, src/scripts/, src/data/, public/
  • backend_paths: (empty)
  • database_paths: (empty)
  • test_frontend_paths: tests/
  • test_backend_paths: (empty)
  • config_paths: astro.config.mjs, tsconfig.json, package.json, .github/workflows/

Commands

Action Command
Install npm install
Dev npm run dev
Build npm run build
Test npm test (Vitest unit) · e2e: npm run test:e2e (Playwright)
Lint npm run check (astro check)
Migrate n/a (static site)

Use these verbatim. Do not invent variants.

Repo pairings

This is a standalone single-repo project. No coordination hub or peer repos.

Cross-repo state (wave status, contracts, handoffs) lives in Engram — never in files. This section holds slow-changing facts only.

SDD workflow

  • No code without an active named change folder (openspec/changes/<name>/ with proposal.md, design.md, tasks.md all present).
  • All implementation uses TDD — tests before code.
  • Multi-wave specs use explicit ## Wave N — [scope] sections; tasks reference the wave slice.
  • Verify before archive — always.
  • Commits reference <change-name> (never an issue number).
  • Brownfield repos: forge:explore runs first to seed Engram topic_key=project/memory.

Gates (non-skippable)

Gate Emoji Trigger Resolved by
Greenfield intake 📥 New greenfield project User confirms PRD or "proceed without"
Plan approval 📋 Any spec/proposal/tasks.md written User approves or returns feedback
Clarification ❓ Agent encounters genuinely blocking ambiguity User answers
Manual test ✅ Validator issues PASS User confirms or reports issues

Interface

Humans use forge:* skills as the default interface. opsx:* is the underlying engine; direct use is an expert exception.

See agent_docs/dispatch-*.md for the full cycle, multi-wave handling, and orchestration detail.

Memory protocol (Engram — required)

Engram is the persistent memory backend. The protocol follows schemas/memory-topics.md and the per-turn budget in agent_docs/memory-budget.md.

Engram access tiers (W4-W5):

  • save-only — validator, tester-front, tester-back, github-ops, agent-sync. mem_save only; prior context arrives via orchestrator briefing cards (engram_context: [...]). If cards are insufficient, return BLOCKED [CONTEXT] missing: <topic_prefix>.
  • search-capable — planner, researcher, frontend, backend, database, agent-prep, devstart, bugfix-pr. Full Engram access. Check briefing cards first; search only if a new domain emerges. Per-turn budget: max 2 mem_search, max 1 L3 fetch, max 1200 mem-tokens injected.
  • orchestrator (main session only) — full access plus exclusive mem_context rights (post-compaction / explicit recall / session resume only).

When to save (mem_save): immediately after a decision, bugfix, pattern, config change, or discovery. Use topic_key per schema namespace for your role. Cross-namespace writes are forbidden and rejected.

Topic schema: <namespace>/<scope>[/<subscope>] — see schemas/memory-topics.md.

Briefing cards pattern: the orchestrator pre-resolves memory cards ONCE per dispatch via bash scripts/sdd-memory-governor.sh --need <X> --topic-prefix <Y> and injects the result as engram_context: [...] in the subagent envelope. Subagents do NOT search on start when cards are present.

mem_context: forbidden for all subagents. Allowed only for the orchestrator after compaction / on explicit user recall / on session resume.

Engram unavailable: continue with [MEMORY] WARNING. Exception: if .engram/ exists in repo, BLOCK with install instructions (see agent_docs/engram-install.md).

Memory sync (orchestrator-owned): after every opsx:archive, the orchestrator runs engram sync to export the change's new memories to .engram/<chunk>.json.gz and commits the chunk with the PR. Without this, memories stay local and teammates cannot consume them. Optional triggers: end of long sessions, before context compaction, before multi-repo handoffs. See .claude/rules/orchestrator-dispatch.md → "Memory Sync".

Boundaries

  • Never edit auto-generated directories (resolved at bootstrap; example: src/generated/, dist/, .next/, target/, __pycache__/).
  • Never commit secrets — .env* files use .example convention.
  • Never bypass approval gates 📋 ✅.
  • See agent_docs/ for: workflow detail, multi-repo setup, skill catalog, MCP integrations, profiles, architecture, Engram install.