ForgeFlow / Reference

User Profile Guidance

The slash commands below are Claude Code entrypoints. Codex users can invoke the corresponding helpers using the runtime path guidance. The profile helper currently defaults to the Claude home even when invoked from another runtime; do not assume installing Codex moves existing preferences into .codex.

Forgeflow user profiles are local advisory preferences about how the user wants Forgeflow to operate and how a specific project should look, feel, and speak.

They are separate from project learnings:

• User operating profile: cross-project preferences for communication, autonomy, validation, release behavior, docs, risk handling, and handoffs.
• Project experience profile: project-local preferences for UI, product copy, accessibility, visual density, and project workflow.

Artifacts

~/.claude/forgeflow/user-operating-profile.jsonl
.forgeflow/<project-name>/project-experience-profile.jsonl

The global file stays under the local Claude home. It is not project state and should not be committed or synced. The project file stays under .forgeflow/<project-name>/ and should remain local unless the project explicitly chooses to share a sanitized version.

Command

Show the current compact profile:

/forgeflow-profile

Run the quality gate:

/forgeflow-profile --check

Review conflicts, scope moves, ask-user prompts, and cleanup actions before agent-heavy work:

/forgeflow-profile-review

Record an explicit operating preference:

/forgeflow-profile --record --scope global --category autonomy --preference "User prefers autonomous safe-slice execution." --evidence "Explicit user instruction." --confidence high --applies-to plan,implement,review,next-step

Record a project look/feel preference:

/forgeflow-profile --record --scope project --category ui --preference "Project screens should feel quiet, dense, and operational." --confidence medium --applies-to plan,implement,review,ui

Categories

Global operating categories:

• communication
• autonomy
• risk
• validation
• release
• docs
• review
• workflow

Project experience categories:

• ui
• product-copy
• accessibility
• workflow

Quality Gate

check-user-profile.js validates:

• schema version
• supported category, scope, source, confidence, and status values
• bounded preference, evidence, guidance, and superseded text
• positive evidence counts
• required replacement text for superseded preferences
• sensitive-content patterns
• unsafe profile files or directories

If the quality gate warns or fails, context packs include a gate note instead of raw profile text.

The checker also reports suggested profile updates and potential conflicts. Suggestions are advisory prompts only; Forgeflow never writes inferred preferences automatically. Conflict warnings mean overlapping active preferences should be clarified or superseded by the user.

Context Injection

build-context-pack.js writes:

.forgeflow/<project-name>/context/latest/user-profile.md

and includes a compact User Profile Guidance section in each agent packet. The packet artifact manifest records whether the profile was included or reduced to metadata-only.

The guidance is advisory only. It never overrides:

• explicit current-turn instructions
• correctness
• security
• accessibility
• validation evidence
• product judgment

What To Record

Good global examples:

• User prefers concise progress updates with exact validation status.
• User prefers autonomous safe-slice execution unless tests fail, risk is high, product judgment is needed, or network/escalation is required.
• User wants README/wiki updates when public behavior changes.

Good project examples:

• This project should use compact operational layouts instead of marketing-style pages.
• Product copy should be plainspoken and avoid tutorial text in the primary UI.
• UI changes should verify keyboard, focus, contrast, loading, error, and mobile states.

Do not record secrets, private URLs, raw settings JSON, source snippets, customer names, or one-off guesses as high-confidence preferences.

Agent Role Use

• Coordinator adapts progress updates, handoffs, autonomy, and next-step framing.
• Product Lead treats profile guidance as product-context hints, not acceptance proof.
• Designer applies project experience preferences only when accessibility and usability remain intact.
• Guardian ignores preferences that would weaken security, privacy, validation, or release gates.
• Builder and Architect use preferences for framing and sequencing, not as code evidence.