@techierathore/techieflow 1.0.0

package/.tfcore/user-guide.md

@@ -0,0 +1,633 @@
+# TechieFlow — User Guide
+
+This guide will help you understand and effectively use the TechieFlow for agile AI-driven planning and development.
+
+## The TechieFlow Plan and Execute Workflow
+
+First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but it's suggested to understand this greenfield first, even if on a simple project before tackling a brownfield project. The TechieFlow needs to be installed to the root of your new project folder. For the planning phase, you can optionally perform it with powerful web agents, potentially resulting in higher quality results at a fraction of the cost it would take to complete if providing your own API key or credits in some Agentic tools. For planning, powerful thinking models and larger context - along with working as a partner with the agents will net the best results.
+
+If you are going to use the TechieFlow with a Brownfield project (an existing project), review **[Working in the Brownfield](./working-in-the-brownfield.md)**.
+
+If the diagrams below don't render, install Markdown All in One along with the Markdown Preview Mermaid Support plugins to VSCode (or one of the forked clones). With these plugins, if you right click on the tab when open, there should be an Open Preview option, or check the IDE documentation.
+
+### The Planning Workflow (Web UI or Powerful IDE Agents)
+
+Before development begins, TechieFlow follows a structured planning workflow that's ideally done in web UI for cost efficiency:
+
+```mermaid
+graph TD
+    A["Start: Project Idea"] --> B{"Optional: Analyst Research"}
+    B -->|Yes| C["Analyst: Brainstorming (Optional)"]
+    B -->|No| G{"Project Brief Available?"}
+    C --> C2["Analyst: Market Research (Optional)"]
+    C2 --> C3["Analyst: Competitor Analysis (Optional)"]
+    C3 --> D["Analyst: Create Project Brief"]
+    D --> G
+    G -->|Yes| E["PM: Create PRD from Brief (Fast Track)"]
+    G -->|No| E2["PM: Interactive PRD Creation (More Questions)"]
+    E --> F["PRD Created with FRs, NFRs, Epics & Stories"]
+    E2 --> F
+    F --> F2{"UX Required?"}
+    F2 -->|Yes| F3["UX Expert: Create Front End Spec"]
+    F2 -->|No| H["Architect: Create Architecture from PRD"]
+    F3 --> F4["UX Expert: Generate UI Prompt for Lovable/V0 (Optional)"]
+    F4 --> H2["Architect: Create Architecture from PRD + UX Spec"]
+    H --> Q{"Early Test Strategy? (Optional)"}
+    H2 --> Q
+    Q -->|Yes| R["QA: Early Test Architecture Input on High-Risk Areas"]
+    Q -->|No| I
+    R --> I["PO: Run Master Checklist"]
+    I --> J{"Documents Aligned?"}
+    J -->|Yes| K["Planning Complete"]
+    J -->|No| L["PO: Update Epics & Stories"]
+    L --> M["Update PRD/Architecture as needed"]
+    M --> I
+    K --> N["📁 Switch to IDE (If in a Web Agent Platform)"]
+    N --> O["PO: Shard Documents"]
+    O --> P["Ready for SM/Dev Cycle"]
+
+    style A fill:#f5f5f5,color:#000
+    style B fill:#e3f2fd,color:#000
+    style C fill:#e8f5e9,color:#000
+    style C2 fill:#e8f5e9,color:#000
+    style C3 fill:#e8f5e9,color:#000
+    style D fill:#e8f5e9,color:#000
+    style E fill:#fff3e0,color:#000
+    style E2 fill:#fff3e0,color:#000
+    style F fill:#fff3e0,color:#000
+    style F2 fill:#e3f2fd,color:#000
+    style F3 fill:#e1f5fe,color:#000
+    style F4 fill:#e1f5fe,color:#000
+    style G fill:#e3f2fd,color:#000
+    style H fill:#f3e5f5,color:#000
+    style H2 fill:#f3e5f5,color:#000
+    style Q fill:#e3f2fd,color:#000
+    style R fill:#ffd54f,color:#000
+    style I fill:#f9ab00,color:#fff
+    style J fill:#e3f2fd,color:#000
+    style K fill:#34a853,color:#fff
+    style L fill:#f9ab00,color:#fff
+    style M fill:#fff3e0,color:#000
+    style N fill:#1a73e8,color:#fff
+    style O fill:#f9ab00,color:#fff
+    style P fill:#34a853,color:#fff
+```
+
+#### Web UI to IDE Transition
+
+**Critical Transition Point**: Once the PO confirms document alignment, you must switch from web UI to IDE to begin the development workflow:
+
+1. **Copy Documents to Project**: Ensure `docs/prd.md` and `docs/architecture.md` are in your project's docs folder (or a custom location you can specify during installation)
+2. **Switch to IDE**: Open your project in your preferred Agentic IDE
+3. **Document Sharding**: Use the PO agent to shard the PRD and then the Architecture
+4. **Begin Development**: Start the Core Development Cycle that follows
+
+#### Planning Artifacts (Standard Paths)
+
+```text
+PRD              → docs/prd.md
+Architecture     → docs/architecture.md
+Sharded Epics    → docs/epics/
+Sharded Stories  → docs/stories/
+QA Assessments   → docs/qa/assessments/
+QA Gates         → docs/qa/gates/
+```
+
+### The Core Development Cycle (IDE)
+
+Once planning is complete and documents are sharded, TechieFlow follows a structured development workflow:
+
+```mermaid
+graph TD
+    A["Development Phase Start"] --> B["SM: Reviews Previous Story Dev/QA Notes"]
+    B --> B2["SM: Drafts Next Story from Sharded Epic + Architecture"]
+    B2 --> S{"High-Risk Story? (Optional)"}
+    S -->|Yes| T["QA: *risk + *design on Draft Story"]
+    S -->|No| B3
+    T --> U["Test Strategy & Risk Profile Created"]
+    U --> B3{"PO: Validate Story Draft (Optional)"}
+    B3 -->|Validation Requested| B4["PO: Validate Story Against Artifacts"]
+    B3 -->|Skip Validation| C{"User Approval"}
+    B4 --> C
+    C -->|Approved| D["Dev: Sequential Task Execution"]
+    C -->|Needs Changes| B2
+    D --> E["Dev: Implement Tasks + Tests"]
+    E --> V{"Mid-Dev QA Check? (Optional)"}
+    V -->|Yes| W["QA: *trace or *nfr for Early Validation"]
+    V -->|No| F
+    W --> X["Dev: Address Coverage/NFR Gaps"]
+    X --> F["Dev: Run All Validations"]
+    F --> G["Dev: Mark Ready for Review + Add Notes"]
+    G --> H{"User Verification"}
+    H -->|Request QA Review| I["QA: Test Architect Review + Quality Gate"]
+    H -->|Approve Without QA| M["IMPORTANT: Verify All Regression Tests and Linting are Passing"]
+    I --> J["QA: Test Architecture Analysis + Active Refactoring"]
+    J --> L{"QA Decision"}
+    L -->|Needs Dev Work| D
+    L -->|Approved| M
+    H -->|Needs Fixes| D
+    M --> N["IMPORTANT: COMMIT YOUR CHANGES BEFORE PROCEEDING!"]
+    N --> Y{"Gate Update Needed?"}
+    Y -->|Yes| Z["QA: *gate to Update Status"]
+    Y -->|No| K
+    Z --> K["Mark Story as Done"]
+    K --> B
+
+    style A fill:#f5f5f5,color:#000
+    style B fill:#e8f5e9,color:#000
+    style B2 fill:#e8f5e9,color:#000
+    style S fill:#e3f2fd,color:#000
+    style T fill:#ffd54f,color:#000
+    style U fill:#ffd54f,color:#000
+    style B3 fill:#e3f2fd,color:#000
+    style B4 fill:#fce4ec,color:#000
+    style C fill:#e3f2fd,color:#000
+    style D fill:#e3f2fd,color:#000
+    style E fill:#e3f2fd,color:#000
+    style V fill:#e3f2fd,color:#000
+    style W fill:#ffd54f,color:#000
+    style X fill:#e3f2fd,color:#000
+    style F fill:#e3f2fd,color:#000
+    style G fill:#e3f2fd,color:#000
+    style H fill:#e3f2fd,color:#000
+    style I fill:#f9ab00,color:#fff
+    style J fill:#ffd54f,color:#000
+    style K fill:#34a853,color:#fff
+    style L fill:#e3f2fd,color:#000
+    style M fill:#ff5722,color:#fff
+    style N fill:#d32f2f,color:#fff
+    style Y fill:#e3f2fd,color:#000
+    style Z fill:#ffd54f,color:#000
+```
+
+## Prerequisites
+
+Before installing TechieFlow, ensure you have:
+
+- **Node.js** ≥ 18, **npm** ≥ 9
+- **Git** installed and configured
+- **(Optional)** VS Code with "Markdown All in One" + "Markdown Preview Mermaid Support" extensions
+
+## Installation
+
+### Optional
+
+If you want to do the planning on the web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPTs:
+
+1. Navigate to `dist/teams/`
+2. Copy `team-fullstack.txt`
+3. Create new Gemini Gem or CustomGPT
+4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
+5. Type `/help` to see available commands
+
+### IDE Project Setup
+
+```bash
+# Interactive installation (recommended)
+# Use ./scaffold-greenfield.sh or ./scaffold-brownfield.sh — see WORKFLOW.html
+```
+
+### OpenCode
+
+TechieFlow integrates with OpenCode via a project-level `opencode.jsonc`/`opencode.json` (JSON-only, no Markdown fallback).
+
+- Installation:
+  - Run # Use ./scaffold-greenfield.sh or ./scaffold-brownfield.sh — see WORKFLOW.html and choose `OpenCode` in the IDE list.
+  - The installer will detect an existing `opencode.jsonc`/`opencode.json` or create a minimal `opencode.jsonc` if missing.
+  - It will:
+    - Ensure `instructions` includes `.tfcore/core-config.yaml` (and each selected expansion pack’s `config.yaml`).
+    - Merge TechieFlow agents and commands using file references (`{file:./.tfcore/...}`), idempotently.
+    - Preserve other top-level fields and user-defined entries.
+
+- Prefixes and collisions:
+  - You can opt-in to prefix agent keys with `techieflow-` and command keys with `techieflow:tasks:` to avoid name collisions.
+  - If a key already exists and is not TechieFlow-managed, the installer will skip it and suggest enabling prefixes.
+
+- What gets added:
+  - `instructions`: `.tfcore/core-config.yaml` plus any selected expansion pack `config.yaml` files, plus `AGENTS.md` (the file OpenCode auto-loads; day-1 tasks emit it).
+  - `agent`: TechieFlow agents from core and selected packs.
+    - `prompt`: `{file:./.tfcore/agents/<id>.md}` (or pack path)
+    - `mode`: `primary` for orchestrators, otherwise `all`
+    - `permission`: `{ edit: allow, bash: allow }` (the deprecated `tools` key auto-normalizes to this; `permission` is the explicit form)
+    - `description`: extracted from the agent’s `whenToUse`
+  - `command`: TechieFlow tasks from core and selected packs.
+    - `template`: `{file:./.tfcore/tasks/<id>.md}` (or pack path)
+    - `description`: extracted from the task’s “Purpose” section
+  - Top-level `permission.bash`: denies every git/gh **write** subcommand (`git commit*`, `git push*`, `git add*`, `git reset*`, `git checkout*`, …, `gh pr create*`, `gh pr merge*`, …) in every mode; read-only git is decided by the plugin-bridged `block-git.sh` (blocked normally, allowed in YOLO — see “YOLO / Goal Mode” below). This is the mechanical gate enforcing “git is manual” (agents’ personas repeat the rule in prose, mirroring the Claude-side `block-git.sh` contract).
+
+- Selected Packages Only:
+  - The installer includes agents and tasks only from the packages you selected in the earlier step (core and chosen packs).
+
+- Refresh after changes:
+  - Re-run:
+    ```bash
+    # Use ./scaffold-greenfield.sh or ./scaffold-brownfield.sh — see WORKFLOW.html
+    ```
+  - The installer safely updates entries without duplication and preserves your custom fields and comments.
+
+- Optional convenience script:
+  - You can add a script to your project’s `package.json` for quick refreshes:
+    ```json
+    {
+      "scripts": {
+        "techieflow:opencode": "see WORKFLOW.html"
+      }
+    }
+    ```
+
+### Codex (CLI & Web)
+
+TechieFlow's full build/runtime workflow is supported in local Codex CLI, IDE,
+and desktop sessions. The scaffold/update scripts install `.codex/` project
+config, custom agents, hooks and rules plus reusable workflows under
+`.agents/skills/`. Trust the repository and review `/hooks` after installation
+or a hook update.
+
+Codex loads the root `AGENTS.md`. Invoke `$techieflow-build`,
+`$techieflow-verify`, `$techieflow-refresh-status`, or name the skill in plain
+language. Literal Claude/OpenCode `*command` and slash names are vocabulary
+aliases, not Codex command registrations.
+
+For an unattended local run:
+
+```bash
+bash .tfcore/utils/tf-goal.sh --harness codex . "<goal>"
+```
+
+Codex cloud cannot automatically reach local `winrun`, Appium hosts, NuGet
+credentials, or already-running services. It is static-only unless equivalent
+infrastructure is explicitly provisioned.
+
+## Special Agents
+
+There are two TechieFlow agents — in the future they'll be consolidated into a single Flow-Master.
+
+### Flow-Master
+
+This agent can do any task or command that all other agents can do, aside from actual story implementation. Additionally, this agent can help explain the TechieFlow when on the web by accessing the knowledge base and explaining anything to you about the process.
+
+If you don't want to bother switching between different agents aside from the dev, this is the agent for you. Just remember that as the context grows, the performance of the agent degrades, therefore it is important to instruct the agent to compact the conversation and start a new conversation with the compacted conversation as the initial message. Do this often, preferably after each story is implemented.
+
+### Flow-Master
+
+This agent should NOT be used within the IDE, it is a heavyweight, special-purpose agent that utilizes a lot of context and can morph into any other agent. This exists solely to facilitate the teams within the web bundles. If you use a web bundle you will be greeted by the TechieFlow Orchestrator.
+
+### How Agents Work
+
+#### Dependencies System
+
+Each agent has a YAML section that defines its dependencies:
+
+```yaml
+dependencies:
+  templates:
+    - prd-template.md
+    - user-story-template.md
+  tasks:
+    - create-doc.md
+    - shard-doc.md
+  data:
+    - techieflow-kb.md
+```
+
+**Key Points:**
+
+- Agents only load resources they need (lean context)
+- Dependencies are automatically resolved during bundling
+- Resources are shared across agents to maintain consistency
+
+#### Agent Interaction
+
+**In IDE:**
+
+```bash
+# Some IDEs, like Cursor or Windsurf for example, utilize manual rules so interaction is done with the '@' symbol
+@pm Create a PRD for a task management app
+@architect Design the system architecture
+@dev Implement the user authentication
+
+# Some IDEs, like Claude Code, use slash commands instead
+/pm Create user stories
+/dev Fix the login bug
+```
+
+#### Interactive Modes
+
+- **Incremental Mode**: Step-by-step with user input
+- **YOLO / Goal Mode**: `*yolo` (or YOLO in any command, an active `/goal`, a `tf-goal.sh` run) — no confirmations or elicitation pauses, deletes + read-only git allowed (git writes never), whole-checklist build passes with an automatic FIX loop, run until the goal is complete; unattended runs via `bash .tfcore/utils/tf-goal.sh <app> "<goal>"` wait out usage-limit windows and resume. Rule: `.tfcore/tasks/_yolo-mode.md`.
+
+## YOLO / Goal Mode (unattended runs)
+
+Full rule: `.tfcore/tasks/_yolo-mode.md`. Background + mechanics: README §12a / DECISIONS 2026-08-21.
+
+### What it means
+
+**YOLO = "I have given you all the permissions and all the access — run until the goal is complete."** Four ways to turn it on, all equivalent:
+
+| You do | What happens |
+|---|---|
+| `*yolo` in any TechieFlow agent | agent runs `bash .tfcore/utils/tf-yolo.sh on` (flag at `.tfcore/.session/yolo.json`) |
+| put **YOLO** anywhere in a command — `*build-phase MyApp yolo` | same, then the command |
+| Claude Code `/goal <condition>` | agent runs `tf-yolo.sh on --source goal`; start the session with `--permission-mode bypassPermissions` (or `auto`) |
+| `bash .tfcore/utils/tf-goal.sh <app> "<goal>"` | the supervisor sets it for you and keeps the run alive (below) |
+
+`*yolo` again (or `tf-yolo.sh off`) turns it off; `tf-yolo.sh status` shows the state.
+
+### What changes
+
+| | Normal | YOLO |
+|---|---|---|
+| `rm` / `rmdir` / `sudo` | prompt | allowed, no prompt (catastrophic `rm -rf /`, `~` still denied) |
+| git/gh **reads** (`status`/`log`/`diff`/`blame`, `gh pr view`) | blocked | allowed |
+| git/gh **writes** (`commit`/`push`/`add`/`reset`/`checkout`/`stash`/`tag`, `gh pr create\|merge`) | blocked | **still blocked — the owner commits** |
+| elicitation, BRD-N confirm pause, phase-boundary pauses, "ask once" questions | pause | agent takes the sensible default, records it in the checklist Remarks, continues |
+| build pass | whole checklist (build-phase §2b) | whole checklist **+ automatic FIX loop** on verifier FAIL rows (§6c, ≤5 cycles) |
+| turn ending | may hand back | only when the goal is complete (`tf-yolo.sh done complete`) or every remaining REQ needs the owner (`done blocked`) |
+
+YOLO does **not** relax the evidence rules: no self-attested `Verified`, PROJECT-STATUS (md + html) still ends every phase, smoke policy unchanged.
+
+### Running a goal unattended (VM recipe)
+
+```bash
+# Claude Code (default) — logs to <app>/.tfcore/.session/goal.log
+bash .tfcore/utils/tf-goal.sh /path/to/App "Take MyApp from its current PROJECT-STATUS to Handoff: build every open REQ, verify all, fix until every row is Verified, then *handoff-phase."
+
+# OpenCode
+bash .tfcore/utils/tf-goal.sh --harness opencode --model opencode-go/kimi-k3 /path/to/App @goal.md
+
+# after a reboot / to continue where it stopped
+bash .tfcore/utils/tf-goal.sh --resume /path/to/App
+```
+
+What the supervisor does for you:
+
+- **Usage limits (5-hour / weekly):** parses the reset time from the limit message (`resets 7pm (Asia/Kolkata)`, `resets in 2h 14m`, `usage limit reached|<epoch>`, weekly `resets Tue 3pm`), sleeps until **reset + 15 min** (`--buffer-min`), logs `RETRY AT …`, then **resumes the same session**. No parseable time → probes with a one-turn `claude -p "Reply OK"` every 15 min (`--probe-min`) until the API answers, then resumes.
+- **Crashes / API errors:** backs off 2 → 30 min and resumes.
+- **Agent stopped without finishing** (asked a question, summarised): re-prompts it after 30 s.
+- **Stops only on the agent's sentinel:** exit `0` complete · `3` blocked — read `.tfcore/.session/goal-done.json` for what the owner must do · `4` max cycles (`--max-cycles`, default 60).
+
+Files (never committed): `.tfcore/.session/goal.log`, `goal.json` (cycle, session id, `resume_at`), `goal-cycle-N.out`, `goal-done.json`.
+
+### If a YOLO run still prompts
+
+1. The app's `.claude/settings.json` predates 2026-08-21 and still has `Bash(rm *)` under `ask` — Claude Code prompts on a settings `ask` in *every* mode, even bypass. Run `update-framework.sh <app>`.
+2. The agent forgot `tf-yolo.sh on` — type `*yolo` again or run it yourself.
+3. It was a git **write** — that prompts for nobody; it is denied by design.
+
+## IDE Integration
+
+### IDE Best Practices
+
+- **Context Management**: Keep relevant files only in context, keep files as lean and focused as necessary
+- **Agent Selection**: Use appropriate agent for task
+- **Iterative Development**: Work in small, focused tasks
+- **File Organization**: Maintain clean project structure
+- **Commit Regularly**: Save your work frequently
+
+## The Test Architect (QA Agent)
+
+### Overview
+
+The QA agent in TechieFlow is not just a "senior developer reviewer" - it's a **Test Architect** with deep expertise in test strategy, quality gates, and risk-based testing. Named Quinn, this agent provides advisory authority on quality matters while actively improving code when safe to do so.
+
+#### Quick Start (Essential Commands)
+
+```bash
+@qa *risk {story}       # Assess risks before development
+@qa *design {story}     # Create test strategy
+@qa *trace {story}      # Verify test coverage during dev
+@qa *nfr {story}        # Check quality attributes
+@qa *review {story}     # Full assessment → writes gate
+```
+
+#### Command Aliases (Test Architect)
+
+The documentation uses short forms for convenience. Both styles are valid:
+
+```text
+*risk    → *risk-profile
+*design  → *test-design
+*nfr     → *nfr-assess
+*trace   → *trace-requirements (or just *trace)
+*review  → *review
+*gate    → *gate
+```
+
+### Core Capabilities
+
+#### 1. Risk Profiling (`*risk`)
+
+**When:** After story draft, before development begins (earliest intervention point)
+
+Identifies and assesses implementation risks:
+
+- **Categories**: Technical, Security, Performance, Data, Business, Operational
+- **Scoring**: Probability × Impact analysis (1-9 scale)
+- **Mitigation**: Specific strategies for each identified risk
+- **Gate Impact**: Risks ≥9 trigger FAIL, ≥6 trigger CONCERNS (see `tasks/risk-profile.md` for authoritative rules)
+
+#### 2. Test Design (`*design`)
+
+**When:** After story draft, before development begins (guides what tests to write)
+
+Creates comprehensive test strategies including:
+
+- Test scenarios for each acceptance criterion
+- Appropriate test level recommendations (unit vs integration vs E2E)
+- Risk-based prioritization (P0/P1/P2)
+- Test data requirements and mock strategies
+- Execution strategies for CI/CD integration
+
+**Example output:**
+
+```yaml
+test_summary:
+  total: 24
+  by_level:
+    unit: 15
+    integration: 7
+    e2e: 2
+  by_priority:
+    P0: 8 # Must have - linked to critical risks
+    P1: 10 # Should have - medium risks
+    P2: 6 # Nice to have - low risks
+```
+
+#### 3. Requirements Tracing (`*trace`)
+
+**When:** During development (mid-implementation checkpoint)
+
+Maps requirements to test coverage:
+
+- Documents which tests validate each acceptance criterion
+- Uses Given-When-Then for clarity (documentation only, not BDD code)
+- Identifies coverage gaps with severity ratings
+- Creates traceability matrix for audit purposes
+
+#### 4. NFR Assessment (`*nfr`)
+
+**When:** During development or early review (validate quality attributes)
+
+Validates non-functional requirements:
+
+- **Core Four**: Security, Performance, Reliability, Maintainability
+- **Evidence-Based**: Looks for actual implementation proof
+- **Gate Integration**: NFR failures directly impact quality gates
+
+#### 5. Comprehensive Test Architecture Review (`*review`)
+
+**When:** After development complete, story marked "Ready for Review"
+
+When you run `@qa *review {story}`, Quinn performs:
+
+- **Requirements Traceability**: Maps every acceptance criterion to its validating tests
+- **Test Level Analysis**: Ensures appropriate testing at unit, integration, and E2E levels
+- **Coverage Assessment**: Identifies gaps and redundant test coverage
+- **Active Refactoring**: Improves code quality directly when safe
+- **Quality Gate Decision**: Issues PASS/CONCERNS/FAIL status based on findings
+
+#### 6. Quality Gates (`*gate`)
+
+**When:** After review fixes or when gate status needs updating
+
+Manages quality gate decisions:
+
+- **Deterministic Rules**: Clear criteria for PASS/CONCERNS/FAIL
+- **Parallel Authority**: QA owns gate files in `docs/qa/gates/`
+- **Advisory Nature**: Provides recommendations, not blocks
+- **Waiver Support**: Documents accepted risks when needed
+
+**Note:** Gates are advisory; teams choose their quality bar. WAIVED requires reason, approver, and expiry date. See `templates/qa-gate-tmpl.yaml` for schema and `tasks/review-story.md` (gate rules) and `tasks/risk-profile.md` for scoring.
+
+### Working with the Test Architect
+
+#### Integration with TechieFlow Workflow
+
+The Test Architect provides value throughout the entire development lifecycle. Here's when and how to leverage each capability:
+
+| **Stage**          | **Command** | **When to Use**         | **Value**                  | **Output**                                                     |
+| ------------------ | ----------- | ----------------------- | -------------------------- | -------------------------------------------------------------- |
+| **Story Drafting** | `*risk`     | After SM drafts story   | Identify pitfalls early    | `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md`        |
+|                    | `*design`   | After risk assessment   | Guide dev on test strategy | `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md` |
+| **Development**    | `*trace`    | Mid-implementation      | Verify test coverage       | `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md`       |
+|                    | `*nfr`      | While building features | Catch quality issues early | `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`         |
+| **Review**         | `*review`   | Story marked complete   | Full quality assessment    | QA Results in story + gate file                                |
+| **Post-Review**    | `*gate`     | After fixing issues     | Update quality decision    | Updated `docs/qa/gates/{epic}.{story}-{slug}.yml`              |
+
+#### Example Commands
+
+```bash
+# Planning Stage - Run these BEFORE development starts
+@qa *risk {draft-story}     # What could go wrong?
+@qa *design {draft-story}   # What tests should we write?
+
+# Development Stage - Run these DURING coding
+@qa *trace {story}          # Are we testing everything?
+@qa *nfr {story}            # Are we meeting quality standards?
+
+# Review Stage - Run when development complete
+@qa *review {story}         # Comprehensive assessment + refactoring
+
+# Post-Review - Run after addressing issues
+@qa *gate {story}           # Update gate status
+```
+
+### Quality Standards Enforced
+
+Quinn enforces these test quality principles:
+
+- **No Flaky Tests**: Ensures reliability through proper async handling
+- **No Hard Waits**: Dynamic waiting strategies only
+- **Stateless & Parallel-Safe**: Tests run independently
+- **Self-Cleaning**: Tests manage their own test data
+- **Appropriate Test Levels**: Unit for logic, integration for interactions, E2E for journeys
+- **Explicit Assertions**: Keep assertions in tests, not helpers
+
+### Gate Status Meanings
+
+- **PASS**: All critical requirements met, no blocking issues
+- **CONCERNS**: Non-critical issues found, team should review
+- **FAIL**: Critical issues that should be addressed (security risks, missing P0 tests)
+- **WAIVED**: Issues acknowledged but explicitly accepted by team
+
+### Special Situations
+
+**High-Risk Stories:**
+
+- Always run `*risk` and `*design` before development starts
+- Consider mid-development `*trace` and `*nfr` checkpoints
+
+**Complex Integrations:**
+
+- Run `*trace` during development to ensure all integration points tested
+- Follow up with `*nfr` to validate performance across integrations
+
+**Performance-Critical:**
+
+- Run `*nfr` early and often during development
+- Don't wait until review to discover performance issues
+
+**Brownfield/Legacy Code:**
+
+- Start with `*risk` to identify regression dangers
+- Use `*review` with extra focus on backward compatibility
+
+### Best Practices
+
+- **Early Engagement**: Run `*design` and `*risk` during story drafting
+- **Risk-Based Focus**: Let risk scores drive test prioritization
+- **Iterative Improvement**: Use QA feedback to improve future stories
+- **Gate Transparency**: Share gate decisions with the team
+- **Continuous Learning**: QA documents patterns for team knowledge sharing
+- **Brownfield Care**: Pay extra attention to regression risks in existing systems
+
+### Output Paths Reference
+
+Quick reference for where Test Architect outputs are stored:
+
+```text
+*risk-profile  → docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
+*test-design   → docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
+*trace         → docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
+*nfr-assess    → docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
+*review        → QA Results section in story + gate file reference
+*gate          → docs/qa/gates/{epic}.{story}-{slug}.yml
+```
+
+## Technical Preferences System
+
+TechieFlow includes a personalization system through the `technical-preferences.md` file located in `.tfcore/data/` - this can help bias the PM and Architect to recommend your preferences for design patterns, technology selection, or anything else you would like to put in here.
+
+### Using with Web Bundles
+
+When creating custom web bundles or uploading to AI platforms, include your `technical-preferences.md` content to ensure agents have your preferences from the start of any conversation.
+
+## Core Configuration
+
+The `.tfcore/core-config.yaml` file is a critical config that enables TechieFlow to work seamlessly with differing project structures, more options will be made available in the future. Currently the most important is the devLoadAlwaysFiles list section in the yaml.
+
+### Developer Context Files
+
+Define which files the dev agent should always load:
+
+```yaml
+devLoadAlwaysFiles:
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/project-structure.md
+```
+
+You will want to verify from sharding your architecture that these documents exist, that they are as lean as possible, and contain exactly the information you want your dev agent to ALWAYS load into its context. These are the rules the agent will follow.
+
+As your project grows and the code starts to build consistent patterns, coding standards should be reduced to include only the standards the agent still needs enforced. The agent will look at surrounding code in files to infer the coding standards that are relevant to the current task.
+
+## Getting Help
+
+- **Workflow reference**: open WORKFLOW.html in a browser, or read README.md
+- **Framework context / maintenance log**: WorkFlow-Context.md
+- **Templates**: .tfcore/templates/v4custom/
+
+
+## Conclusion
+
+Remember: TechieFlow is designed to enhance your development process, not replace your expertise. Use it as a powerful tool to accelerate your projects while maintaining control over design decisions and implementation details.