diff --git a/.uf/dewey/learnings/blog-agents-md-quality-1.md b/.uf/dewey/learnings/blog-agents-md-quality-1.md new file mode 100644 index 0000000..80e049c --- /dev/null +++ b/.uf/dewey/learnings/blog-agents-md-quality-1.md @@ -0,0 +1,9 @@ +--- +tag: blog-agents-md-quality +category: reference +created_at: 2026-05-03T18:47:59Z +identity: blog-agents-md-quality-1 +tier: draft +--- + +When writing blog posts about /agent-brief and AGENTS.md quality for the Unbound Force website, the 5-tier scoring rubric has a downgrade rule that is easy to miss: if Tier 1C sections are applicable (project has a constitution or spec framework) but missing, the score is downgraded by one level. This means an otherwise Strong AGENTS.md becomes Adequate. The upstream source at .opencode/command/agent-brief.md lines 273-279 defines the rubric, and lines 251-267 define the Tier 1C quality checks. The 12 structural checks include: 5 Tier 1 section presence, 2 Tier 1C conditional checks, build code block presence, directory tree accuracy, constitution reference, spec framework reference, cross-framework bridge, and branch protection instruction. diff --git a/content/blog/agents-md-quality.md b/content/blog/agents-md-quality.md new file mode 100644 index 0000000..09f6456 --- /dev/null +++ b/content/blog/agents-md-quality.md @@ -0,0 +1,140 @@ +--- +title: "Your AI Agent's First Read — Why AGENTS.md Quality Determines Code Quality" +description: "AGENTS.md is the first file every AI coding agent reads. A weak one means the agent starts with wrong assumptions. /agent-brief creates or audits yours with a 5-tier scoring rubric." +lead: "Garbage in, garbage out. Your AGENTS.md is the prompt that shapes every line of AI-generated code. Audit it, do not guess." +slug: "agents-md-quality" +date: 2026-05-03T00:00:00+00:00 +draft: false +weight: 55 +toc: true +categories: ["Engineering"] +tags: ["agents-md", "context", "quality", "agent-brief"] +contributors: ["Unbound Force"] +--- + +## The Problem + +Every AI coding agent — Claude Code, Cursor, OpenCode, Copilot — reads a context file at the start of each session. That file tells the agent how to build the project, what conventions to follow, where the tests live, and what constraints to respect. In the Unbound Force ecosystem, this file is `AGENTS.md`. Other tools use `.cursorrules`, `CLAUDE.md`, or similar formats. The name varies; the problem is universal. + +When this file is weak, missing, or stale, the agent starts every session with wrong assumptions. It guesses at build commands. It invents conventions that conflict with the team's standards. It writes code that compiles and passes linting but does not fit — wrong error handling patterns, wrong directory structure, wrong import organization. The code looks correct to a tool but wrong to a human reviewer. + +The fix is not "be more specific in your prompts." The fix is treating your project context file as production infrastructure — structured, auditable, and maintained. + +## What Makes a Good AGENTS.md + +A complete AGENTS.md has three tiers of sections, each serving a different purpose: + +### Tier 1: Essential Sections + +Every AGENTS.md needs these. Without them, the agent is guessing at fundamentals. + +| Section | Purpose | What to Include | +|---------|---------|-----------------| +| **Project Overview** | What is this project? | Type (CLI, library, API), domain, license | +| **Build & Test Commands** | How do I build and test? | Exact commands with flags, in fenced code blocks | +| **Project Structure** | Where is everything? | Directory tree with annotations | +| **Code Conventions** | How should I write code? | Commit format, naming, error handling, import order | +| **Technology Stack** | What tools and versions? | Language versions, key dependencies, frameworks | + +These five sections are the minimum. An agent with all five can produce code that builds, follows conventions, and lands in the right directory. + +### Tier 1C: Context-Sensitive Sections + +These sections are triggered by project signals. They are essential *when applicable* but irrelevant otherwise. + +- **Constitution / Governance**: Only needed when the project has a constitution file (`.specify/memory/constitution.md`). Summarizes the governing principles that all work must align with. +- **Spec Framework**: Only needed when the project uses Speckit (`specs/` directory) or OpenSpec (`openspec/config.yaml`). Describes the specification workflow and pipeline stages. + +An AGENTS.md that omits a Tier 1C section when the trigger exists is incomplete — the agent will not know about governance constraints or spec requirements that other tools enforce. + +### Tier 2: Advanced Sections + +These sections differentiate a strong AGENTS.md from an adequate one. They capture the institutional knowledge that takes weeks to discover. + +| Section | Purpose | +|---------|---------| +| **Architecture** | Patterns, design decisions, module boundaries | +| **Testing Conventions** | Test organization, fixture patterns, coverage expectations | +| **Git & Workflow** | Branching strategy, PR requirements, branch protection | +| **Behavioral Constraints** | Things agents must NEVER do (often more impactful than positive instructions) | + +A Behavioral Constraints section is particularly valuable. Negative instructions like "never modify coverage thresholds to make tests pass" and "never commit directly to main" prevent entire categories of agent mistakes. + +## The 5-Tier Scoring Rubric + +How do you know if your AGENTS.md is good enough? The `/agent-brief` command uses a deterministic scoring rubric: + +| Score | Criteria | +|-------|----------| +| **Excellent** | 5/5 Tier 1 + 4/4 Tier 2 + all applicable Tier 1C | +| **Strong** | 5/5 Tier 1 + 2-3/4 Tier 2 | +| **Adequate** | 4-5/5 Tier 1 | +| **Weak** | 2-3/5 Tier 1 | +| **Missing** | 0-1/5 Tier 1 | + +If Tier 1C sections are applicable (the project has a constitution or spec framework) but missing, the score is downgraded by one level. An otherwise "Strong" AGENTS.md becomes "Adequate" if it ignores governance constraints that the project enforces. + +The scoring is structural, not subjective. It counts section headers, checks for code blocks in the Build section, verifies that directory trees match the actual filesystem, and confirms that constitution references exist when a constitution is present. Twelve checks in total — no AI judgment involved in the score. + +## Audit, Don't Guess + +```text +/agent-brief audit +``` + +The audit command reads your existing AGENTS.md and produces a quality report: + +- **Section coverage**: Which Tier 1 / 1C / 2 sections are present vs. missing +- **Quality metrics**: Line count, build code blocks, directory tree accuracy, staleness checks +- **Overall score**: One of the 5 tiers, with justification +- **Recommendations**: For each missing section, generated content you can review and apply + +The audit is read-only — it does not modify your file. You decide what to accept. + +## Create from Project Signals + +```text +/agent-brief create +``` + +When no AGENTS.md exists, `/agent-brief` analyzes your project and generates one from actual project data: + +- **`go.mod`**, **`package.json`**, **`Cargo.toml`** → language, dependencies, versions +- **`Makefile`**, **`.github/workflows/`** → exact build, test, and lint commands (CI files are the source of truth) +- **`.golangci.yml`**, **`ruff.toml`**, **`.eslintrc`** → linter rules and conventions +- **`README.md`**, **`LICENSE`**, **`.git/config`** → project description, license, organization +- **`.specify/memory/constitution.md`**, **`specs/`**, **`openspec/`** → governance and spec framework (Tier 1C triggers) + +The generated file has two quality levels: Tier 1 sections are filled from actual project data (concrete commands, real directory trees, detected conventions). Tier 2 sections are stubs with detailed TODO comments explaining what to fill and why it matters. The result is a complete skeleton that you can review and flesh out. + +## Bridge Files + +AGENTS.md is the canonical project context file, but different AI tools read different files. `/agent-brief` ensures cross-tool compatibility by verifying bridge files: + +- **CLAUDE.md**: Should contain `@AGENTS.md` to import the project context into Claude Code sessions +- **.cursorrules**: Should reference AGENTS.md for Cursor IDE integration + +Bridge file creation is handled by `uf init`. If bridge files are missing or misconfigured, `/agent-brief` reports the status and suggests running `uf init` to create them. + +## This Applies to Every AI Coding Tool + +AGENTS.md is not an Unbound Force concept — it is a convention adopted across multiple AI coding tools. Claude Code reads `CLAUDE.md` and `AGENTS.md`. Cursor reads `.cursorrules`. Copilot reads context from repository structure. The names differ, but the principle is the same: the quality of your context file determines the quality of your AI-generated code. + +The section taxonomy (Tier 1 / 1C / 2), the scoring rubric, and the structural checks apply regardless of which tool you use. If your `.cursorrules` file has no build commands and no project structure, your Cursor agent is guessing — just like an OpenCode agent with a weak AGENTS.md. + +## Get Started + +Install the Unbound Force CLI and audit your project: + +```bash +brew install unbound-force/tap/unbound-force +/agent-brief audit +``` + +Find out where your project context is weak. Fix it. Watch the quality of AI-generated code improve. + +## See Also + +- [Common Workflows](/docs/getting-started/common-workflows/) -- `/agent-brief` create and audit documentation +- [Quick Start](/docs/getting-started/quick-start/) -- Install and verify the toolchain +- [Developer Guide](/docs/getting-started/developer/) -- Daily workflow with the `uf` CLI diff --git a/openspec/changes/blog-agents-md-quality/.openspec.yaml b/openspec/changes/blog-agents-md-quality/.openspec.yaml new file mode 100644 index 0000000..977c2b7 --- /dev/null +++ b/openspec/changes/blog-agents-md-quality/.openspec.yaml @@ -0,0 +1,2 @@ +schema: unbound-force +created: 2026-05-03 diff --git a/openspec/changes/blog-agents-md-quality/design.md b/openspec/changes/blog-agents-md-quality/design.md new file mode 100644 index 0000000..0593c19 --- /dev/null +++ b/openspec/changes/blog-agents-md-quality/design.md @@ -0,0 +1,44 @@ +## Context + +The website documents `/agent-brief` in `common-workflows.md` (PR #74) with create/audit modes, 5-tier rubric, and bridge file management. Issue #65 provides a narrative angle emphasizing broad appeal — AGENTS.md quality matters for any AI coding agent, not just Unbound Force users. + +## Goals / Non-Goals + +### Goals +- Write a blog post following the BA-001 narrative arc +- Lead with "garbage in, garbage out" per BA-007 — frame from the universal problem of AI agent context quality +- Include the 5-tier scoring rubric as a self-assessment tool +- Explain the section taxonomy (Tier 1 / Tier 1C / Tier 2) so readers understand what makes a complete AGENTS.md +- Cover bridge files (CLAUDE.md, .cursorrules) for cross-tool reach +- Frame broadly — useful for Claude Code, Cursor, Copilot users, not just Unbound Force + +### Non-Goals +- Duplicate the full command reference (flags, doctor integration) — link to common-workflows docs +- Tutorial-style AGENTS.md writing guide (different content type) +- Comparison with other context file formats (e.g., Cursor rules files) + +## Decisions + +1. **Slug and filename**: `agents-md-quality` — emphasizes the quality dimension. File at `content/blog/agents-md-quality.md`. + +2. **Universal opening**: Start with a problem any developer using AI agents faces — not tool-specific. Mention Claude Code, Cursor, Copilot by name to signal broad relevance and improve search discoverability. + +3. **Rubric as centerpiece**: The 5-tier scoring rubric is the key takeaway — readers should be able to self-assess their own AGENTS.md after reading the post. + +4. **Section taxonomy as education**: Explain what Tier 1 / Tier 1C / Tier 2 sections are. This teaches the reader what a complete AGENTS.md looks like, independent of any specific tool. + +5. **Frontmatter pattern**: Follow existing blog post frontmatter. + +6. **Cross-references**: Link to common-workflows docs where `/agent-brief` is documented (PR #74, if merged). + +## Content Sources + +Authoritative upstream source: +- `/agent-brief` command: `unbound-force/unbound-force/.opencode/command/agent-brief.md` + +All technical claims must be verified against the upstream command file at implementation time. + +## Risks / Trade-offs + +- **Risk**: The "broad appeal" framing could make the post feel generic. Mitigated by including specific `/agent-brief` examples alongside the universal principles. +- **Trade-off**: Depth vs. breadth. Chose breadth — the post teaches the concept of AGENTS.md quality and introduces `/agent-brief` as one implementation. Deep `/agent-brief` usage is covered in the reference docs. diff --git a/openspec/changes/blog-agents-md-quality/proposal.md b/openspec/changes/blog-agents-md-quality/proposal.md new file mode 100644 index 0000000..19f7da8 --- /dev/null +++ b/openspec/changes/blog-agents-md-quality/proposal.md @@ -0,0 +1,57 @@ +## Why + +AGENTS.md is the first file every AI coding agent reads. A weak or missing AGENTS.md means the agent starts with wrong assumptions about conventions, build commands, and project structure — leading to code that compiles but does not fit. This is a "garbage in, garbage out" problem that affects every team using AI coding agents, regardless of which agent they use (Claude Code, Cursor, OpenCode, Copilot). + +`/agent-brief` creates AGENTS.md from project signals or audits existing ones with a 5-tier scoring rubric. The command is documented in `common-workflows.md` (PR #74), but there is no narrative content explaining why AGENTS.md quality matters and how to improve it. This topic has broad search appeal — "AGENTS.md best practices" and "AI agent context files" are queries that reach beyond Unbound Force users. + +This change addresses [GitHub issue #65](https://github.com/unbound-force/website/issues/65). + +## What Changes + +A new blog post at `content/blog/agents-md-quality.md` with the narrative arc: + +1. **The problem** — AGENTS.md as the prompt that shapes all agent output; weak context → weak code +2. **What makes a good AGENTS.md** — the section taxonomy: Tier 1 (essential), Tier 1C (context-sensitive), Tier 2 (advanced) +3. **Audit, don't guess** — `/agent-brief audit` with 5-tier scoring rubric and 12 structural checks +4. **Create from signals** — `/agent-brief create` analyzes go.mod, Makefile, CI config, README +5. **Bridge files** — CLAUDE.md, .cursorrules, and cross-tool compatibility +6. **Broad applicability** — works for any AI coding agent, not just OpenCode + +## Capabilities + +### New Capabilities +- `blog/agents-md-quality`: Blog post on AGENTS.md quality and the `/agent-brief` command + +### Modified Capabilities +- None + +### Removed Capabilities +- None + +## Impact + +- 1 new blog post (Markdown content file) +- No layout, style, or configuration changes +- Cross-references to common-workflows docs and getting-started pages + +## Constitution Alignment + +Assessed against the Unbound Force website project constitution (`.specify/memory/constitution.md`). + +### I. Content Accuracy + +**Assessment**: PASS + +All technical claims (5-tier rubric, 12 structural checks, section taxonomy, bridge file behavior) will be verified against the upstream implementation at `unbound-force/unbound-force/.opencode/command/agent-brief.md` at implementation time. The broad applicability claim (works for any AI agent) is accurate — AGENTS.md is a convention adopted across multiple tools. + +### II. Minimal Footprint + +**Assessment**: PASS + +Single Markdown blog post file. No custom layouts, CSS, JavaScript, or dependencies. + +### III. Visitor Clarity + +**Assessment**: PASS + +Follows the BA-001 narrative arc. Leads with a universal problem ("your AI agent's first read determines code quality") that applies to any team using AI coding agents. The 5-tier rubric gives visitors a concrete self-assessment tool. diff --git a/openspec/changes/blog-agents-md-quality/specs/blog-post.md b/openspec/changes/blog-agents-md-quality/specs/blog-post.md new file mode 100644 index 0000000..cd44798 --- /dev/null +++ b/openspec/changes/blog-agents-md-quality/specs/blog-post.md @@ -0,0 +1,55 @@ +## ADDED Requirements + +### Requirement: agents-md-blog-post + +The website MUST have a blog post at `content/blog/agents-md-quality.md` explaining why AGENTS.md quality determines AI-generated code quality and introducing `/agent-brief` as a quality assessment tool. + +#### Scenario: user reads agents-md blog post + +- **GIVEN** a user navigates to the AGENTS.md quality blog post +- **WHEN** the page renders +- **THEN** the post MUST follow the BA-001 narrative arc: problem (weak context → weak code), approach (structured AGENTS.md with section taxonomy), evidence (5-tier rubric, structural checks), and call to action +- **AND** the post MUST lead with benefit framing per BA-007 (universal problem applicable to any AI coding agent) +- **AND** the post MUST mention at least two AI coding tools beyond OpenCode (e.g., Claude Code, Cursor, Copilot) to signal broad relevance + +### Requirement: agents-md-blog-rubric + +The blog post MUST include the 5-tier scoring rubric. + +#### Scenario: user self-assesses their AGENTS.md + +- **GIVEN** a user reads the scoring rubric section +- **WHEN** they compare their AGENTS.md against the criteria +- **THEN** all 5 tiers MUST be listed: Excellent, Strong, Adequate, Weak, Missing +- **AND** each tier MUST include its criteria summary + +### Requirement: agents-md-blog-taxonomy + +The blog post MUST explain the section taxonomy (Tier 1 / Tier 1C / Tier 2). + +#### Scenario: user understands what to include + +- **GIVEN** a user reads the section taxonomy +- **WHEN** they plan their AGENTS.md content +- **THEN** Tier 1 sections (essential) MUST be listed with examples +- **AND** Tier 1C sections (context-sensitive) MUST be explained as conditionally triggered +- **AND** Tier 2 sections (advanced) MUST be listed + +### Requirement: agents-md-blog-frontmatter + +The blog post MUST use valid Hugo/Doks blog frontmatter consistent with existing posts. + +#### Scenario: blog post builds correctly + +- **GIVEN** the blog post file exists with frontmatter +- **WHEN** `npm run build` is executed +- **THEN** the build MUST succeed with no errors +- **AND** the frontmatter MUST include: title, description, lead, slug, date, draft (false), weight, toc, categories, tags, contributors + +## MODIFIED Requirements + +_None._ + +## REMOVED Requirements + +_None._ diff --git a/openspec/changes/blog-agents-md-quality/tasks.md b/openspec/changes/blog-agents-md-quality/tasks.md new file mode 100644 index 0000000..f216cb7 --- /dev/null +++ b/openspec/changes/blog-agents-md-quality/tasks.md @@ -0,0 +1,31 @@ +## 1. Create blog post file with frontmatter + +- [x] 1.1 Create `content/blog/agents-md-quality.md` with Hugo/Doks blog frontmatter (title, description, lead, slug, date, draft: false, weight, toc, categories: ["Engineering"], tags: ["agents-md", "context", "quality", "agent-brief"], contributors) + +## 2. Write the problem and solution sections + +- [x] 2.1 Write "The Problem" section: AGENTS.md as the prompt shaping all agent output — weak context leads to code that compiles but does not fit. Frame universally (Claude Code, Cursor, Copilot, OpenCode) +- [x] 2.2 Read upstream source file (`unbound-force/unbound-force/.opencode/command/agent-brief.md`) to verify section taxonomy, rubric tiers, and structural checks before writing +- [x] 2.3 Write section taxonomy: Tier 1 (essential: Project Overview, Build & Test, Project Structure, Code Conventions, Technology Stack), Tier 1C (context-sensitive: Constitution, Spec Framework), Tier 2 (advanced: Architecture, Testing, Git & Workflow, Behavioral Constraints) + +## 3. Write rubric and audit sections + +- [x] 3.1 Write 5-tier scoring rubric table: Excellent, Strong, Adequate, Weak, Missing — with criteria for each tier +- [x] 3.2 Write `/agent-brief audit` section: 12 structural checks, actionable recommendations, context-sensitive detection +- [x] 3.3 Write `/agent-brief create` section: project signal analysis (go.mod, Makefile, CI config, README), hybrid template + LLM approach + +## 4. Write supplementary sections + +- [x] 4.1 Write bridge files section: CLAUDE.md (@AGENTS.md import), .cursorrules, cross-tool compatibility +- [x] 4.2 Write call to action: install command verified at implementation time + +## 5. Cross-references and verification + +- [x] 5.1 Add cross-reference links to common-workflows docs and getting-started pages — only link to pages that exist at implementation time +- [x] 5.2 Run `npm run build` and confirm no build errors +- [x] 5.3 Verify the blog post appears in the blog listing page +- [x] 5.4 Verify all internal links resolve (no dead links) +- [ ] 5.5 Run `npm run dev` and verify the post renders correctly +- [ ] 5.6 Verify both light and dark mode rendering + +