ALLEN-yzz/project-role-workflow

Project Role Workflow

Design the project and its collaboration system around confirmed needs instead of forcing a fixed architecture or number of sessions. Roles may be merged, split, added, or removed as scope changes, but the user confirms the final arrangement.

Workflow

1. Determine the project mode before proposing roles or files:

   • Treat the folder as an existing project when it contains substantive requirements, source, build configuration, or project documentation. Inspect it read-only: read the effective AGENTS.md, README/product overview, current status, relevant requirements, repository layout, build/test commands, and Git state.
   • Treat it as a greenfield project when it has no substantive project files, even if it contains only version-control metadata, ignore files, or placeholders. Read references/greenfield-project-design.md and conduct progressive requirements discovery before choosing an architecture, technology stack, roles, or directory tree.
   • If the evidence is ambiguous, show what exists and ask whether it should be preserved as the starting point. Never overwrite an apparently empty folder without checking hidden and untracked content.

2. Establish the project basis:

   • For an existing project, identify frontend/backend boundaries, deployable units, external systems, real-environment operations, security risk, data migration risk, and independent verification needs.
   • For a greenfield project, discuss the user's desired outcome, users, core flows, prioritized functions, data and permission model, integrations, operating environment, quality constraints, and delivery boundaries. Ask focused questions in manageable rounds rather than presenting one exhaustive questionnaire.
   • Summarize confirmed requirements, non-goals, constraints, unresolved decisions, and explicit assumptions. Obtain user confirmation of this project brief before designing the architecture and directory structure.
   • When ambiguous terms could change scope, ownership, data meaning, or acceptance, draft a shared-language list in the conversation: preferred term, definition, disallowed synonyms, and boundary example. Do not create project files for it until the brief is confirmed; preserve it only when it will materially help the project.
   • Do not assume the current project needs the same technology, architecture, or roles as a previous project.

3. For a confirmed greenfield brief, propose the project design before creating files:

   • Explain the proposed architecture, deployable units, major boundaries, and consequential technology choices. Show alternatives and tradeoffs where the user's answer could materially change the structure.
   • When a consequential choice remains uncertain, propose a time-bounded decision investigation before committing to the design. Its output states the question, alternatives, evidence from appropriate primary sources, unknowns, and a recommended decision. Use a throwaway prototype only when it can cheaply answer the uncertainty; treat it as evidence, not production code or an approved scaffold.
   • Provide a complete directory tree proportional to the confirmed functions, with concise purposes for important directories and non-obvious root files.
   • Map the requested functions to their owning modules, tests, data or integration boundaries, and deployment units so the tree is traceable to the brief.
   • Include only applicable concerns such as frontend, backend, shared contracts, persistence and migrations, tests, documentation, automation, infrastructure, and operations. Do not add layers or folders merely to make the tree look comprehensive.
   • Mark deferred or optional areas clearly. Ask the user to confirm or revise the architecture and directory plan before initializing any scaffold.

4. Propose a role plan before creating collaboration documents:

   • Show each proposed role, why it is needed, owned files/systems, inputs, outputs, and handoff target.
   • Map the role plan to work items or decision items where it improves execution: each item has one owner, explicit dependencies or blocking edges, affected files/systems, and observable completion conditions. This is a plan, not authorization to create tracker issues or change external state.
   • Mark roles that can reasonably be merged and roles that should remain independent.
   • Show the stage order and any safe parallel work.
   • Ask the user to confirm, add, remove, split, or merge roles. If the user already specified the exact roles and asks for immediate initialization, use them directly.

5. After confirmation, initialize only the approved scope:

   • A directory proposal is not permission to create an application scaffold. Confirm whether the user wants design documents only, collaboration documents, or the approved project scaffold as well.
   • For a greenfield project, preserve the confirmed brief and architecture/directory decisions in the project documentation when initialization is requested.
   • Extend rather than overwrite an existing AGENTS.md.
   • Create one role document per selected role under the project's established documentation convention, normally docs/roles/.
   • Create or update a shared workflow status document and the handoff/report documents required by the selected roles.
   • Keep agent-facing instructions navigable: the root AGENTS.md carries only cross-project rules and routing; put module, role, and operation detail near the relevant code or document. Include real entry points, commands, tests, owners, and links to the source of truth rather than duplicating generic guidance.
   • Define a fixed first-line identity label for each user-visible role response.
   • Preserve project-specific commands, security rules, dirty-worktree boundaries, and existing authority rules.

6. Keep collaboration document-first:

   • Chats do not share reliable conversational context. Decisions, current status, freeze values, deployment state, defects, and handoffs must live in project files.
   • Every role reads the root instructions, its role document, current status, the relevant requirement section, and the incoming handoff before acting.
   • Each file area, API contract, database, deployment object, or real environment has one active owner at a time.
   • Do not let two sessions edit the same files or operate the same environment concurrently.

7. Use proportional validation gates:

   • Separate implementation self-test, independent acceptance, deployment/readiness, and deployment-after verification when those stages exist.
   • A successful build, plausible model text, service start, or tool discovery is not evidence of the requested end-to-end effect.
   • Default acceptance uses batch-defect mode: record ordinary P1/P2 issues and continue independent safe checks, then return one defect batch for one implementation cycle and one refreeze.
   • Stop immediately for credential leakage, unauthorized writes, data damage, production/isolated-environment confusion, or any condition where continuing would corrupt evidence or expand risk.
   • A failed prerequisite may block dependent checks; mark them blocked rather than passing them by inference.

8. Adapt the role structure when scope changes:

   • Split a role only when independent ownership, expertise, or deployment/testing boundaries justify the coordination cost.
   • Merge roles for small work when independence is not materially valuable.
   • Before changing roles mid-project, settle open handoffs, file ownership, active environment ownership, and uncommitted changes.

Role Selection

Read references/role-catalog.md when analyzing or revising the role plan. It contains merge/split criteria and a proposal format. Do not copy every catalog role into a project.

Project Documents

Read references/collaboration-documents.md when initializing or revising project workflow files. Use assets/AGENTS.workflow-section.template.md as a starting asset, adapting placeholders and omitting unused sections.

For an empty project, do not read the existing-project references as a substitute for requirements discovery. Use the confirmed project brief and directory plan as the source of truth for subsequent role and document design.

Decision Evidence

Use a shared-language document, decision record, research note, prototype report, or dependency map only when it resolves a real coordination or design uncertainty. Keep each artifact connected to the confirmed brief, current owner, and next decision. Do not turn exploratory material into an implementation requirement until the user confirms it.

Non-Negotiable Boundaries

• Role design never grants permission to deploy, restart, migrate, delete, rotate credentials, commit, push, publish, or message external parties.
• Requirements approval, test success, and prior authorization do not authorize a new real-environment mutation.
• Preserve existing user changes and unrelated dirty-worktree content.
• Empty or nearly empty does not mean disposable: inspect hidden files and obtain confirmation before creating or replacing project artifacts.
• Do not copy business-specific names, paths, ports, credentials, acceptance IDs, or architecture decisions from another project unless the user explicitly asks.
• A testing role does not silently fix product code. An operations role does not silently change product requirements. An implementation role does not declare independent acceptance.

Handoff Quality

Every handoff must state:

• role identity and stage;
• confirmed objective and requirement/version references;
• completed work and observable evidence;
• exact changed/frozen scope;
• tests run and results;
• unresolved defects and unverified boundaries;
• protected objects and forbidden actions;
• next role and its executable acceptance conditions.

Keep status concise and current; keep append-only historical evidence in the appropriate report rather than duplicating the full history into every role prompt.