Support project-level context files in PRD and design workflows

[eranco74]

Summary

The PRD and design workflows should natively support loading project-specific context files that extend (not replace) the workflow's built-in behavior. This enables projects to inject domain knowledge — personas, cross-cutting dimensions, review expectations, decomposition heuristics — that the generic workflows can't know about.

Motivation

In the OSAC project, we found that PRDs and design documents consistently missed important project-specific dimensions:

• Services — Features apply to different service tiers (BMaaS, CaaS, VMaaS) with different behavior per service
• Personas — OSAC has 4 canonical personas (Cloud Provider Admin, Cloud Infrastructure Admin, Tenant Admin, Tenant User) that user stories must address
• Cross-cutting concerns — Tenant onboarding, inventory backends, networking backends, storage integration, installation impact — each feature must declare what's in/out of scope for each
• Review patterns — Institutional knowledge about common reviewer feedback themes and anti-patterns
• Decomposition heuristics — Project-specific complexity assessment dimensions and cross-repo dependency mapping

None of this belongs in the generic workflow — it's OSAC-specific. But without it, PRDs and designs are incomplete and get caught in review.

Current workaround

We added a CLAUDE.md instruction telling both workflows to read files from .design/context/:

### Feature Dimensions Context

Both `/prd:ingest` and `/design:ingest` must read all files in `.design/context/` during their ingest phase:

- **`osac-dimensions.md`** — Cross-cutting dimensions, services, personas
- **`review-patterns.md`** — Common EP reviewer feedback themes and anti-patterns

This works because both controllers read CLAUDE.md at startup. But it's fragile — it relies on the AI following an indirect instruction rather than having a built-in convention.

Proposal

Add a conventional lookup path for project-level context files, similar to how .design/templates/ already works for template overrides:

Convention: .design/context/*.md

Any markdown file in .design/context/ is project-level context that extends the workflow's behavior. These files are additive — they don't replace any built-in behavior, they provide additional context for the AI to consider.

Integration points

The context files should be loaded at these phases:

Phase	How context is used
/prd:ingest	After ingesting requirements, check context files for dimensions the requirements don't address. Flag gaps in Initial Observations.
/prd:clarify	Use dimensions/personas from context files to generate targeted clarifying questions (e.g., "Which services are in scope?", "What does each persona see?")
/prd:draft	Use review patterns to anticipate reviewer expectations. Ensure all declared dimensions are addressed.
/design:ingest	Load context files alongside CLAUDE.md and docs/ in Step 4 (Read Project Configuration)
/design:draft	Cross-check dimension coverage. Use review patterns for self-review.
/design:decompose	Use decomposition heuristics (if present) for complexity assessment and dependency mapping

Implementation

The changes are small and surgical:

1. prd/skills/ingest.md — Add a step after compiling raw requirements: "Check for .design/context/*.md files. If they exist, read them and use their dimensions to identify gaps in the Initial Observations section."

2. prd/skills/clarify.md — In Step 2 (Gap Analysis), add: "If .design/context/ files exist, also check requirements against any project-specific dimensions, personas, or checklists they define."

3. design/skills/ingest.md — In Step 4 (Read Project Configuration), add .design/context/*.md to the list alongside CLAUDE.md and docs/.

4. design/skills/draft.md — In Step 2 (Read Source Material), add: "Read .design/context/*.md files if they exist — use review patterns for self-review and dimension checklists for coverage verification."

5. design/skills/decompose.md — Add: "If .design/context/ contains decomposition heuristics, use them to inform complexity assessment and task extraction."

Key principles

• Extension, not override — Context files add to the workflow's behavior, they never replace built-in steps or templates
• Optional — Projects without .design/context/ work exactly as before
• Convention over configuration — No config file needed, just drop .md files in the directory
• Project-specific — The content is domain knowledge that varies by project, not generic workflow logic

Example context files

From OSAC (already in use via CLAUDE.md workaround):

• osac-dimensions.md — Services, personas, cross-cutting dimensions (tenant onboarding, inventory, networking, storage, installation), milestone scoping
• review-patterns.md — Common reviewer feedback themes, anti-patterns, EP reference library, key reviewers by domain

References

• Template override convention: .design/templates/ (already supported)
• PRD template override convention: .prd/templates/ (already supported)
• OSAC implementation: https://github.com/osac-project/osac-workspace/tree/main/.design/context/

[amir-yogev-gh]

Thanks for the detailed writeup, @eranco74. The problem is real — PRDs and designs that miss project-specific dimensions get caught in review, and that's wasteful. But I think the proposed solution creates unnecessary complexity when the existing mechanism already handles this.

CLAUDE.md/AGENTS.md is the project context layer — that's what it's for.

The proposal acknowledges that the CLAUDE.md workaround works today. I'd argue it's not a workaround — it's the intended pattern. CLAUDE.md is the universal "project brain" that every AI tool and every workflow reads. Building a parallel .design/context/ loading convention means:

• Two places to look for project-specific guidance instead of one
• Workflow-coupled context — .design/context/ only works with PRD and design workflows, while CLAUDE.md works with everything (Claude Code, Cursor, any AI tool, any skill)
• Convention sprawl — if PRD and design get their own context directories, every workflow will eventually want one

The "fragile" argument doesn't hold up. CLAUDE.md instructions aren't "indirect" — they're the primary mechanism for project context. If the workflows aren't reliably applying CLAUDE.md guidance, that's a bug in the workflow to fix, not a reason to build a second context system.

Modularity is already solved with progressive disclosure. In flightctl, we use nested AGENTS.md files to keep context modular and load it only when relevant:

AGENTS.md                        # repo-wide conventions, build commands, pointers
├── api/AGENTS.md                # OpenAPI specs, codegen, versioning rules
├── internal/agent/AGENTS.md     # agent reconciliation, lifecycle, testing patterns
├── deploy/AGENTS.md             # Helm, quadlets, kind deployment
├── docs/AGENTS.md               # doc structure, style, linting
└── test/AGENTS.md               # unit, integration, e2e test conventions

The root AGENTS.md provides the high-level orientation and points to area-specific files. When the AI works in internal/agent/, it picks up the agent-specific guidance automatically. This is progressive disclosure — the AI gets the right context at the right depth without loading everything upfront.

OSAC could do the same — put personas, dimensions, and review patterns in dedicated files and reference them from the root:

### Project Context
@.design/context/osac-dimensions.md
@.design/context/review-patterns.md

Every tool and workflow picks them up automatically — no per-workflow integration needed.

AGENTS.md is also vendor-agnostic. Unlike a .design/context/ convention that only our workflows understand, AGENTS.md is supported by the vast majority of AI tools — Claude Code, Cursor, Windsurf, Copilot, and others all read it. Project context stored in AGENTS.md works everywhere, today and as new tools emerge. Building a workflow-specific context path fragments that knowledge into a format only two workflows can consume.

What I'd suggest instead:

1. Keep the OSAC context files where they are (.design/context/ is a fine location for the files themselves)
2. Reference them from CLAUDE.md/AGENTS.md via @ references
3. Use nested AGENTS.md files for progressive disclosure if context grows
4. If any workflow isn't applying CLAUDE.md/AGENTS.md guidance effectively, file that as a bug against the specific workflow

This keeps one universal, vendor-agnostic context layer instead of fragmenting project knowledge across workflow-specific conventions.