Project structure standard

BUILD / CURATE THE BLUEFLY PROJECT STRUCTURE, CONTEXT, DOCUMENTATION, AND REPOSITORY HYGIENE STANDARD.

GOAL:

EVERY BLUEFLY PROJECT SHOULD FEEL LIKE IT BELONGS TO THE SAME ENGINEERING SYSTEM.

A new human or agent entering any repository should be able to understand, quickly:

WHAT THIS PROJECT IS
WHY IT EXISTS
WHAT PROBLEM IT SOLVES
WHAT THE CURRENT VISION IS
WHAT THE CURRENT OBJECTIVES ARE
WHAT WORK IS ACTIVE
WHAT CONTEXT IS REQUIRED
WHAT DOCS ARE LOCAL VS GLOBAL
WHO OWNS THE PROJECT
WHAT IT DEPENDS ON
WHAT CONSUMES IT
HOW TO BUILD IT
HOW TO TEST IT
HOW TO RELEASE IT
HOW TO OPERATE IT
WHAT NOT TO TOUCH
WHAT IS REUSABLE
WHAT IS PROJECT-SPECIFIC

No slop.
No duplicate doctrine.
No mystery files.
No random agent notes.
No copied global docs.
No personal paths.
No one-off structures.
No stale planning files disconnected from Beads.

============================================================
CANONICAL STANDARD
============================================================

Create or curate:

BluCity-Docs/Engineering-Standard/standards/project-structure-standard.md

Also create/reuse a machine-readable standard if one already exists.

If an existing standard owns this topic:

CURATE IT.

Do not create duplicate doctrine.

============================================================
CORE MODEL
============================================================

Each project has TWO documentation/context layers:

1. PROJECT-LOCAL CONTEXT
2. BLUEFLY GLOBAL DOCTRINE

PROJECT REPO answers:

WHAT IS TRUE ABOUT THIS PROJECT?

BluCity-Docs answers:

WHAT IS TRUE ACROSS BLUEFLY?

Do not mix them.

============================================================
WHAT BELONGS IN BLUCITY-DOCS
============================================================

BluCity-Docs owns cross-project doctrine, standards, architecture, and durable
organization-wide decisions.

Examples:

engineering standards
GitLab standards
project structure standard
branch/release doctrine
CI doctrine
security doctrine
Drupal doctrine
Gas City doctrine
authority model
context-plane model
runtime architecture
portable-host architecture
cross-project integration architecture
company-wide agent rules
shared naming conventions
shared worktree rules
shared package rules
shared documentation rules
shared secret/auth rules
cross-project ADRs
canonical platform architecture
estate-wide catalogs/reference material

If the statement applies to MANY projects:

BluCity-Docs is probably the owner.

============================================================
WHAT BELONGS IN THE PROJECT
============================================================

The project repo owns context specific to that project.

Examples:

project purpose
project vision
project objective
project scope
current architecture
project-specific decisions
project-specific API
project-specific development instructions
project-specific build/test commands
project-specific dependencies
project-specific integration notes
project-specific deployment behavior
project-specific examples
project-specific schemas
project-specific ADRs when they do not affect the wider estate
project-specific agent context

If the statement answers:

"WHAT IS UNIQUE ABOUT THIS PROJECT?"

it belongs locally.

============================================================
NO COPY OF GLOBAL DOCTRINE INTO EVERY REPO
============================================================

Do NOT copy entire sections of BluCity-Docs into:

README.md
AGENTS.md
.agents/context/*
CLAUDE.md
project docs

Instead:

REFERENCE CANONICAL DOCTRINE.

Example:

Project AGENTS.md should say:

"Follow the Bluefly Project Structure Standard, GitLab Standard, and
appropriate Drupal/Gas City doctrine."

Then state only:

THIS PROJECT'S EXCEPTIONS / SPECIAL RULES.

============================================================
MANDATORY .agents DIRECTORY
============================================================

Every active project should have:

.agents/

This is the project-local durable agent context surface.

It is NOT a scratch folder.

It is NOT an agent transcript dump.

Recommended baseline:

.agents/
├── README.md
├── context/
├── plans/
├── decisions/
├── receipts/
└── generated/

Use existing Bluefly conventions if names already exist.

Do not create duplicate structures such as:

.agent/
agents-context/
ai-context/
.prompts/
.claude/context/

when `.agents/` owns the durable project agent context.

============================================================
.AGENTS/README.md
============================================================

This is the entry point for agents.

It should explain:

PROJECT=
PURPOSE=
VISION=
PRIMARY_OBJECTIVE=
CURRENT_STATE=
SOURCE_AUTHORITY=
WORK_AUTHORITY=
PROJECT_PROFILE=

CANONICAL_GLOBAL_DOCS=
LOCAL_CONTEXT=
BEADS_USAGE=
BUILD_COMMANDS=
TEST_COMMANDS=
RELEASE_FLOW=
IMPORTANT_BOUNDARIES=

Keep it concise.

Do not turn this into the project README duplicated for agents.

============================================================
.AGENTS/CONTEXT/
============================================================

This contains durable PROJECT-SPECIFIC context.

Examples:

project-overview.md
architecture.md
dependencies.md
integrations.md
runtime.md
data-model.md
api.md
drupal.md
deployment.md
known-boundaries.md

Only create files that represent real distinct concepts.

Do NOT dump arbitrary notes here.

Every context file must answer:

WHAT IS THIS CONTEXT?
WHO OWNS IT?
HOW FRESH IS IT?
WHERE DOES ITS SOURCE TRUTH LIVE?

============================================================
PROJECT VISION FILE
============================================================

Every active project needs one concise durable project vision.

Recommended:

.agents/context/vision.md

This should contain:

MISSION
VISION
WHY_THIS_PROJECT_EXISTS
WHAT_SUCCESS_LOOKS_LIKE
WHAT_THIS_PROJECT_OWNS
WHAT_THIS_PROJECT_DOES_NOT_OWN
TARGET_USERS/CONSUMERS
LONG_TERM_DIRECTION

Keep it stable.

Do NOT use it as a task list.

============================================================
PROJECT OBJECTIVE FILE
============================================================

Every active project needs a current objective.

Recommended:

.agents/context/objectives.md

This should contain:

CURRENT_PRIMARY_OBJECTIVE=
SECONDARY_OBJECTIVES=
SUCCESS_CRITERIA=
CURRENT_MAJOR_CONSTRAINTS=
CURRENT_DEPENDENCIES=
OUT_OF_SCOPE=

Objectives should be curated, not appended forever.

Do not make it a chronological journal.

Beads remain the authoritative work graph.

============================================================
BEADS ARE THE WORK GRAPH
============================================================

Do NOT create:

TODO.md
tasks.md
backlog.md
work-list.md
agent-tasks.md
random planning checklists

as parallel work systems.

BEADS owns:

WHAT WORK EXISTS
STATUS
PRIORITY
DEPENDENCIES
ASSIGNMENT
COMPLETION

Project docs own:

VISION
OBJECTIVES
ARCHITECTURAL INTENT
CONTEXT

The rule:

VISION / OBJECTIVES
→ durable project context

TASKS / EXECUTION
→ Beads

Do not duplicate Beads into Markdown.

============================================================
.AGENTS/PLANS/
============================================================

Plans are allowed only for substantial bounded execution plans.

Examples:

migration plan
release transition
major refactor plan
architecture convergence plan

Plan files must include:

BEAD=
PURPOSE=
SCOPE=
OWNER=
STATUS=
CREATED=
SUPERSEDED_BY=
COMPLETION_CRITERIA=

Plans should be disposable after the work is finished.

When complete:

either delete them
or retain only if they serve as valuable historical design evidence.

Git history is the archive.

Do not accumulate years of stale plans.

============================================================
.AGENTS/DECISIONS/
============================================================

Project-local durable decisions may live here if they are too narrow for
BluCity-Docs.

Use them only for project-specific decisions.

If the decision affects:

multiple projects
Bluefly architecture
platform authority
shared CI
shared security
shared runtime

then it belongs in BluCity-Docs decision records instead.

Decision rule:

LOCAL PROJECT IMPACT
→ .agents/decisions/

ESTATE / PLATFORM IMPACT
→ BluCity-Docs/Engineering-Standard/decision-records/

Do not duplicate the same ADR in both places.

============================================================
.AGENTS/RECEIPTS/
============================================================

Do NOT dump every agent response here.

Receipts are durable only when they prove something significant.

Examples:

migration acceptance
release proof
security remediation
runtime convergence proof
schema migration verification

Receipt files must be:

bounded
dated
linked to a Bead/MR/commit
factual
not conversational

Use:

YYYY-MM-DD-short-description.md

Do not store raw chat transcripts.

============================================================
.AGENTS/GENERATED/
============================================================

Only generated machine context belongs here.

Examples:

generated dependency graph
generated API inventory
generated component inventory
generated runtime manifest

Every file must state:

GENERATED=YES
GENERATOR=
SOURCE=
REFRESH_COMMAND=

Do not manually edit generated files.

============================================================
AGENTS.md
============================================================

Every project should have root:

AGENTS.md

This is the operational contract.

It should contain:

PROJECT SCOPE
SOURCE OWNER
EDIT BOUNDARIES
FORBIDDEN PATHS
WORKTREE RULES
BEADS RULES
CI RULES
BUILD/TEST
RELEASE TARGET
UPSTREAM DOC LOOKUP
PACKAGE OWNERSHIP
SPECIAL SAFETY RULES

It should also point to:

.agents/README.md
.agents/context/
BluCity-Docs global standards

Do NOT put long vision/architecture documents directly in AGENTS.md.

============================================================
README.md
============================================================

README.md is the human entry point.

It should answer:

WHAT IS THIS?
WHY DOES IT EXIST?
HOW DO I USE IT?
HOW DO I DEVELOP IT?
HOW DO I TEST IT?
HOW DO I RELEASE IT?
WHERE ARE THE PROJECT DOCS?
WHERE ARE THE AGENT DOCS?

Keep it concise.

Link to:

.agents/context/vision.md
project docs
BluCity-Docs standards

============================================================
DOCS/ DIRECTORY
============================================================

Use project-local `docs/` only for documentation that belongs to the project.

Examples:

API reference
developer setup
integration guide
package usage
project architecture
user/operator guide

Do not copy Bluefly standards there.

If documentation is:

GLOBAL STANDARD
→ BluCity-Docs

PROJECT-SPECIFIC
→ repo docs/

If it is agent-oriented project context:
→ .agents/context/

============================================================
DISTINCTION: DOCS VS AGENT CONTEXT
============================================================

docs/
= durable human/project documentation

.agents/context/
= concise machine-operational context agents need to act correctly

They may link to each other.

Do not duplicate content.

Example:

docs/architecture.md
contains full architecture explanation.

.agents/context/architecture.md
contains:
- canonical architecture doc link
- important agent boundaries
- high-level current state
- source authority

Do NOT copy the full architecture file.

============================================================
MANDATORY PROJECT IDENTITY
============================================================

Every project must establish:

PROJECT_NAME=
PROJECT_PATH=
PROJECT_PROFILE=
PURPOSE=
VISION=
PRIMARY_OBJECTIVE=
SOURCE_AUTHORITY=
WORK_AUTHORITY=
PACKAGE_ID=
RUNTIME_ID=
OWNER=

This may live in:

.agents/context/project.md

or existing machine-readable metadata.

Do not invent another metadata file if current Bluefly standards already have
one.

============================================================
PROJECT PROFILE
============================================================

Classify each repo:

INTERNAL_LIBRARY
PUBLIC_LIBRARY
SERVICE
CLI
DRUPAL_CONTRIB_MODULE
DRUPAL_PRIVATE_MODULE
DRUPAL_THEME
DRUPAL_RECIPE
DRUPAL_SITE_TEMPLATE
DRUPAL_SITE
FRONTEND_LIBRARY
AGENT_PROJECT
SKILLS_PROJECT
CI_COMPONENT_LIBRARY
IAC
CONTAINER_RUNTIME
DOCUMENTATION
POLICY
SCHEMA_REGISTRY
ARCHIVED

Every profile inherits the same baseline.

Profile-specific differences are intentional.

============================================================
BASELINE TOP-LEVEL STRUCTURE
============================================================

Typical active project:

README.md
AGENTS.md
.gitignore
.gitattributes
.gitlab-ci.yml
CODEOWNERS

.agents/
docs/                 # only when required
src/                  # ecosystem-dependent
tests/
config/               # if needed
schemas/              # if project owns schemas

ecosystem package files

Do NOT force irrelevant directories.

============================================================
COMMON ALLOWED DIRECTORIES
============================================================

.agents/
src/
tests/
docs/
config/
schemas/
templates/
scripts/
bin/
assets/
examples/
fixtures/
migrations/
packages/
components/
recipes/
web/
infra/
deploy/
tools/

Every directory must have a clear purpose.

============================================================
FORBIDDEN SLOP DIRECTORIES
============================================================

Do not create:

stuff/
misc/
random/
new/
new2/
final/
old/
backup/
scratch/
temp/
tmp/
working/
archive/
_archive/
legacy-copy/
do-not-delete/

Git is the archive.

============================================================
NO RANDOM MARKDOWN
============================================================

Flag files like:

notes.md
thoughts.md
ideas.md
agent-notes.md
todo.md
todo2.md
plan-final.md
architecture-v2.md
new-plan.md
status.md

unless they have a real defined owner and role.

Move useful content into:

.agents/context/
.agents/plans/
docs/
BluCity-Docs

Then delete the slop.

============================================================
NAMING CONSISTENCY
============================================================

Use ecosystem-native naming.

General:

directories:
lowercase
kebab-case unless ecosystem convention dictates otherwise

Markdown:
lowercase-kebab-case

Conventional uppercase:
README.md
AGENTS.md
LICENSE
SECURITY.md
CONTRIBUTING.md
CODEOWNERS
CHANGELOG.md

Drupal machine names may use underscores.

Do not arbitrarily rename ecosystem-defined identifiers.

============================================================
DRY PROJECT DOCTRINE
============================================================

Before adding anything:

SEARCH FIRST.

Search:

same repo
BluCity-Docs
gitlab_components
blu-cli
BluCity-Packs
shared skills
Studio UI
Drupal contrib
existing package repos
api-schema-registration
ContractPlane
ContextControl
agent-docker
IaC

If capability exists:

REUSE IT.

Do not duplicate:

CI
docs
schemas
scripts
components
policies
context
agent instructions
test helpers
release logic

============================================================
ONE OWNER
============================================================

Every capability has one owner.

Examples:

shared CI
→ gitlab_components

estate CLI
→ blu-cli

global doctrine
→ BluCity-Docs

shared UI
→ Studio UI

schema registry
→ api-schema-registration

Drupal reusable module
→ its producer repo

project-specific docs
→ project repo

project-specific context
→ .agents/context

work/tasks
→ Beads

============================================================
NO PARALLEL PLANNING SYSTEM
============================================================

This is critical.

Do NOT maintain:

Beads
+
TODO.md
+
project-plan.md
+
agent-plan.md
+
GitLab Issues

all as competing truth.

Beads = authoritative execution graph.

GitLab Issues may exist for public/customer collaboration where appropriate.

Markdown plans = bounded execution support only.

============================================================
CONTEXT FRESHNESS
============================================================

Each `.agents/context/*.md` file should include:

SOURCE=
LAST_REVIEWED=
AUTHORITY=

where useful.

Agents must distinguish:

CURATED PROJECT CONTEXT
LIVE RUNTIME STATE
GITLAB STATE
BEADS STATE
GENERATED STATE

Do not treat a six-month-old context file as live runtime truth.

============================================================
PROJECT CONTEXT ENTRYPOINT
============================================================

.agents/README.md should tell agents:

READ FIRST:

1. AGENTS.md
2. .agents/context/vision.md
3. .agents/context/objectives.md
4. applicable project context
5. current Bead
6. relevant BluCity-Docs standards
7. current source/runtime evidence

Do not load every file blindly.

============================================================
VISION VS OBJECTIVE VS PLAN VS BEAD
============================================================

VISION:
Where the project is going.

OBJECTIVES:
What outcomes matter now.

PLAN:
How a bounded major change will be executed.

BEAD:
Actual unit of work.

Do not mix them.

============================================================
BLUCITY-DOCS CROSS-LINKING
============================================================

Every project should identify the global standards it inherits.

Examples:

PROJECT_STRUCTURE_STANDARD=
GITLAB_STANDARD=
CI_STANDARD=
SECURITY_STANDARD=
DRUPAL_STANDARD=
GAS_CITY_STANDARD=

Do not hardcode local filesystem paths in portable docs.

Use canonical repo URLs or portable workspace references.

============================================================
PROJECT ARCHITECTURE
============================================================

Project-specific architecture belongs locally if it only applies to that project.

Use:

docs/architecture.md

or equivalent.

If architecture defines the wider Bluefly platform:

move it to BluCity-Docs.

Project context should then link to the global architecture.

============================================================
PROJECT API DOCUMENTATION
============================================================

Producer API docs belong in the producer project.

OpenAPI source belongs with the producer when it is authoritative.

External/reference API schemas belong in the shared API schema reference/catalog.

Do not copy third-party schemas into project docs.

============================================================
PROJECT DECISION RULE
============================================================

Ask:

WOULD ANOTHER PROJECT NEED TO OBEY THIS?

YES:
BluCity-Docs.

NO:
Project repo.

Ask:

IS THIS A PROJECT-SPECIFIC FACT AN AGENT NEEDS?

YES:
.agents/context/

Ask:

IS THIS HUMAN DEVELOPER/USER DOCUMENTATION?

YES:
docs/

Ask:

IS THIS WORK?

YES:
Beads.

============================================================
GENERATED HARNESS FILES
============================================================

Harness-specific files such as:

.claude/*
Cursor rules
Codex config
OpenCode config

should not become independent doctrine.

If needed:

CANONICAL AGENT POLICY
→ generate harness projections

Do not maintain five manual copies.

============================================================
NO PERSONAL PATHS
============================================================

No durable docs/context should contain:

~
/home/ubuntu
/Volumes/...

unless explicitly documenting one host-specific adapter.

Use:

[WORKSPACE-ROOT]
project root
environment variables
relative paths

============================================================
WORKTREE LAW
============================================================

Inside DDEV:

/var/www/worktrees

Outside DDEV:

Gas City manages worktrees.

Do not create repo-local worktree directories.

============================================================
SCRIPTS
============================================================

scripts/ is not a dumping ground.

Each script must have:

OWNER=
PURPOSE=
CALLER=
TEST=
LONG_TERM_HOME=

Reusable:
move to shared tool.

============================================================
GENERATED FILE LAW
============================================================

Every generated file:

GENERATED=YES
SOURCE=
GENERATOR=
DO_NOT_EDIT=

Do not mix generated and hand-authored content in one ambiguous file.

============================================================
ARCHIVE LAW
============================================================

No source archive folders.

Delete obsolete files.

Git preserves history.

Use an archive only when the runtime requires historical artifacts.

============================================================
FIRST PROJECT
============================================================

Start with:

blueflyio/master-template

because it should define the minimal project baseline.

Audit:

README
AGENTS
.agents/
context
docs
CI
CODEOWNERS
naming
slop
duplicate files
machine-local files
old agent files
GitHub residue

Make master-template the clean BASE.

Do NOT fill it with profile-specific files.

============================================================
PROFILE VALIDATION
============================================================

Then validate against representative projects:

gitlab_components
→ CI component library

BluCity-Docs
→ documentation project

blu-cli
→ CLI

api-schema-registration
→ tool

one Drupal contrib-ready module

one Drupal private module

one Drupal site

agent-docker
→ runtime

IaC
→ infrastructure

ContextControl
→ Drupal product/context platform

This proves the standard across real project types.

============================================================
PER-PROJECT AUDIT LOOP
============================================================

For each project:

IDENTIFY
→ PROFILE
→ INVENTORY
→ VISION/OBJECTIVE REVIEW
→ CONTEXT REVIEW
→ DOC OWNERSHIP REVIEW
→ STRUCTURE REVIEW
→ DUPLICATION REVIEW
→ CLEANUP
→ TEST
→ MR
→ CI
→ VERIFY
→ RECEIPT
→ NEXT

ONE PROJECT AT A TIME.

============================================================
PROJECT RECEIPT
============================================================

PROJECT=
PROFILE=

PURPOSE=
VISION=
PRIMARY_OBJECTIVE=

README=
AGENTS=

AGENTS_DIR=
AGENTS_README=
VISION_DOC=
OBJECTIVES_DOC=

LOCAL_CONTEXT_FILES=
LOCAL_PLAN_FILES=
LOCAL_DECISIONS=
LOCAL_RECEIPTS=
GENERATED_CONTEXT=

GLOBAL_DOCS_REFERENCED=
GLOBAL_DOCS_DUPLICATED=

ROOT_FILES=
ROOT_DIRS=

MISSING_REQUIRED_FILES=
UNEXPECTED_FILES=
UNEXPECTED_DIRS=

DUPLICATE_DOCS=
DUPLICATE_CONTEXT=
DUPLICATE_CI=
DUPLICATE_SCHEMAS=
DUPLICATE_SCRIPTS=

TODO_FILES=
STALE_PLANS=
AGENT_TRANSCRIPTS=
PERSONAL_PATHS=
TEMP_FILES=
BACKUP_FILES=
GITHUB_RESIDUE=
HARNESS_SLOP=

BEADS_USED=YES|NO
PARALLEL_TASK_SYSTEM_FOUND=YES|NO

SOURCE_OWNER_CLEAR=
WORK_OWNER_CLEAR=
DOC_OWNER_CLEAR=
CONTEXT_OWNER_CLEAR=

FILES_MOVED=
FILES_REMOVED=
FILES_RENAMED=

MR=
PIPELINE=

STRUCTURE_COMPLIANT=YES|NO
CONTEXT_COMPLIANT=YES|NO
DOCS_COMPLIANT=YES|NO

EXCEPTIONS=

PROJECT_COMPLETE=YES|NO

Do not move to next project until:

PROJECT_COMPLETE=YES

============================================================
FINAL LAW
============================================================

EVERY PROJECT HAS:

PURPOSE.
VISION.
CURRENT OBJECTIVE.
AGENT ENTRYPOINT.
PROJECT CONTEXT.
CLEAR DOC OWNERSHIP.
CLEAR SOURCE OWNERSHIP.
CLEAR WORK OWNERSHIP.

BEADS OWNS WORK.

.agents/context OWNS PROJECT-SPECIFIC AGENT CONTEXT.

docs/ OWNS PROJECT-SPECIFIC HUMAN DOCUMENTATION.

BluCity-Docs OWNS BLUEFLY-WIDE DOCTRINE.

AGENTS.md OWNS THE PROJECT OPERATING CONTRACT.

README.md OWNS THE HUMAN ENTRY POINT.

ONE OWNER.
NO DUPLICATION.

NO RANDOM NOTES.
NO PARALLEL TODO SYSTEM.
NO STALE PLANS.
NO COPIED GLOBAL DOCS.
NO AGENT TRANSCRIPTS.
NO MYSTERY FILES.
NO PERSONAL PATHS.
NO SLOP.

IF IT IS GLOBAL:
MOVE IT TO BLUCITY-DOCS.

IF IT IS PROJECT-SPECIFIC CONTEXT:
PUT IT IN .agents/context.

IF IT IS HUMAN PROJECT DOCUMENTATION:
PUT IT IN docs/.

IF IT IS WORK:
PUT IT IN BEADS.

IF IT HAS NO OWNER OR PURPOSE:
DELETE IT.