[alekshaugom]

Preview, not ready to merge. AGENTS.md points agents to the harper-architecture skill, which is proposed in HarperFast/skills#125. Mark this ready once that skill is merged and released.

Why

Skills load on demand, but the decision about which services to use happens before any skill loads. AGENTS.md is read at the start of every agent session, so it's where we can say "Harper is the whole backend" before the agent starts planning a stack. npm create harper already installs the Harper skills into .agents/skills/. This file makes sure the agent reads the right one first.

What this adds

Two files in templates-shared/all/, applied to every template:

• AGENTS.md covers:
  • Harper is the whole backend.
  • Read .agents/skills/harper-architecture/SKILL.md before planning, or run npm run agent:skills:update if it's missing.
  • Record one capability decision per requirement.
  • Read the matching harper-best-practices rule before implementing.
  • A stop list (packages like redis, express, socket.io, @aws-sdk/client-s3; a second server; sessions in a Map; hand-rolled password hashing).
  • Project layout, commands, and the test rule.
• CLAUDE.md: one line, @AGENTS.md, so Claude Code loads the same instructions.

Coverage:

• Gets both files: all 11 templates in the shared fan-out (react, vue, and vanilla, including their TS and SSR variants), plus early-hints.
• Studio templates: pick them up automatically, because they're built from the template-* dirs.
• Next.js templates are not included yet. They aren't in the templates-shared fan-out, and their layout differs (app/, root schema.graphql, @harperfast/nextjs). They need either a joined fan-out or their own variant. The test excludes them by name, so the gap can't go unnoticed.
• early-hints is legacy and unpublished, so it gets the files but they don't fully match it. I can exclude it the same way it's already excluded from _github, if preferred.

Test: the existing per-template integration test, which runs the real CLI, now checks that AGENTS.md points to harper-architecture and that CLAUDE.md is @AGENTS.md. 41 test files, 366 tests pass.

Feedback wanted

Please comment on the wording of AGENTS.md now, even though it can't merge yet. It's the first thing every agent reads in a new Harper project.

Related

• feat: add harper-architecture skill skills#125 feat: add harper-architecture skill (blocks this PR)
• feat: add replaces field and Instead-of line to rules skills#126 feat: add replaces field and Instead-of line to rules

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request adds AI agent instructions (AGENTS.md and CLAUDE.md) to several Harper application templates and updates the integration tests to assert their presence. Feedback on the pull request suggests adding 'early-hints' to the WITHOUT_AGENT_INSTRUCTIONS_TEMPLATES set in the integration tests if it is a legacy template that should be excluded from receiving these instructions.

[dawsontoth]

This shouldn't be the purview of this repo, copying stuff into the templates from the skills. If the skills repo isn't placing things in the right place, then let's update it to place things in the right place. Don't hard code things into the templates that the templates won't keep up to date, spreading logic across multiple repos, complicating updates.