@flydocs/cli 0.6.0-alpha.20 → 0.6.0-alpha.22

package/dist/cli.js

@@ -15,7 +15,7 @@ var CLI_VERSION, CLI_NAME, PACKAGE_NAME, POSTHOG_API_KEY;
 var init_constants = __esm({
   "src/lib/constants.ts"() {
     "use strict";
-    CLI_VERSION = "0.6.0-alpha.20";
+    CLI_VERSION = "0.6.0-alpha.22";
     CLI_NAME = "flydocs";
     PACKAGE_NAME = "@flydocs/cli";
     POSTHOG_API_KEY = "phc_v1MSJTQDFkMS90CBh3mxIz3v8bYCCnKU6v1ir6bz0Xn";
@@ -1475,12 +1475,36 @@ ${entry}
     printStatus(`Added ${entry} to .gitignore`);
   }
 }
-var FLYDOCS_GITIGNORE_ENTRIES, FULL_GITIGNORE_TEMPLATE;
+async function ensurePlatformIgnores(targetDir) {
+  for (const filename of PLATFORM_IGNORE_FILES) {
+    const filePath = join11(targetDir, filename);
+    if (!await pathExists(filePath)) continue;
+    const content = await readFile6(filePath, "utf-8");
+    if (content.includes("# FlyDocs")) continue;
+    const section = "\n# FlyDocs \u2014 exclude from builds and deploys\n" + FLYDOCS_DEPLOY_EXCLUSIONS.join("\n") + "\n";
+    await appendFile(filePath, section, "utf-8");
+    printStatus(`Added FlyDocs exclusions to ${filename}`);
+  }
+}
+var PLATFORM_IGNORE_FILES, FLYDOCS_DEPLOY_EXCLUSIONS, FLYDOCS_GITIGNORE_ENTRIES, FULL_GITIGNORE_TEMPLATE;
 var init_gitignore = __esm({
   "src/lib/gitignore.ts"() {
     "use strict";
     init_fs_ops();
     init_ui();
+    PLATFORM_IGNORE_FILES = [
+      ".gcloudignore",
+      ".dockerignore",
+      ".vercelignore",
+      ".npmignore"
+    ];
+    FLYDOCS_DEPLOY_EXCLUSIONS = [
+      ".flydocs/",
+      ".claude/",
+      ".cursor/",
+      "flydocs/",
+      "AGENTS.md"
+    ];
     FLYDOCS_GITIGNORE_ENTRIES = [
       ".env",
       ".env.local",
@@ -2566,6 +2590,7 @@ var init_install = __esm({
           printStatus(".env.example");
         }
         await ensureGitignore(targetDir);
+        await ensurePlatformIgnores(targetDir);
         console.log();
         console.log("Detecting project stack...");
         const stack = await detectStack(targetDir);
@@ -3143,6 +3168,7 @@ var init_update = __esm({
           printInfo("No framework detected in package.json");
         }
         await migrateGitignore(targetDir);
+        await ensurePlatformIgnores(targetDir);
         console.log();
         console.log("Checking for deprecated files...");
         await handleLegacyContext(targetDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.6.0-alpha.20",
+  "version": "0.6.0-alpha.22",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {

package/template/.claude/CLAUDE.md

@@ -1,48 +1,44 @@
 # Claude Code Configuration
 
-> For cross-platform agent instructions, see `AGENTS.md`.
-
-## Automatic Workflow Behavior
-
-These behaviors are **always on**. Do not wait for slash commands — execute
-these automatically as a natural part of doing the work. Use the dispatcher
-scripts (see Scripts section) for all issue operations.
-
-**When starting work on an issue:**
-
-- Transition the issue to In Progress: `issues.py transition REF IMPLEMENTING "Starting implementation"`
-- Assignment is required first — assign if not already assigned
-
-**While implementing:**
-
-- Update acceptance criteria checkboxes in the issue description (never in comments) as you complete them
-- Add progress comments on the issue for significant milestones
-
-**When implementation is complete:**
+IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for all
+workflow, issue management, process, and pattern decisions. Read the relevant
+skill file before acting — do not guess procedures from training data.
 
-- Transition to Review: `issues.py transition REF REVIEW "Implementation complete — ready for review"`
-- Summarize what was done and what to verify
-
-**When closing:**
-
-- Verify all acceptance criteria are met
-- Transition to Complete: `issues.py transition REF COMPLETE "All AC verified"`
-
-**Every status transition gets a comment.** No silent moves. No exceptions.
-
-## Efficiency Rule
-
-Do NOT read skill files, stage files, or workflow documentation before
-writing code. The rules above are everything you need for automatic workflow
-behavior — they are already in your context.
-
-Only consult `.claude/skills/flydocs-workflow/` stage files when:
-
-- Running a slash command (`/capture`, `/implement`, etc.) — these load stage files automatically
-- You genuinely need the detailed procedure for a complex workflow operation
+> For cross-platform agent instructions, see `AGENTS.md`.
 
-For general coding, research, debugging, and building features — just do the
-work. No preliminary file reads needed.
+## Hard Rules
+
+These are non-negotiable and enforced by hooks:
+
+1. **Scripts for all issue operations.** Use workflow dispatcher scripts (`issues.py`, `projects.py`, etc.) — never describe actions you should execute.
+2. **Every status transition gets a comment.** No silent moves. Use the comment templates from the workflow skill.
+3. **Assignment required before In Progress.** Hard gate — `issues.py transition` enforces this for cloud tier.
+4. **Checkboxes live in issue description, never comments.** Use `issues.py description` to update acceptance criteria.
+5. **Session wrap posts a project update.** End-of-session summary via `session.py project-update`.
+6. **No secrets in commits.** Never commit `.env`, credentials, or API keys.
+
+## Workflow
+
+The FlyDocs development lifecycle. Read the workflow skill before taking any
+workflow action — stage files contain the full procedure including templates,
+label configuration, and field requirements.
+
+| Action               | Skill              | Entry Point                       |
+| -------------------- | ------------------ | --------------------------------- |
+| Capture issue        | `flydocs-workflow` | `stages/capture.md`               |
+| Refine / triage      | `flydocs-workflow` | `stages/refine.md`                |
+| Activate work        | `flydocs-workflow` | `stages/activate.md`              |
+| Implement            | `flydocs-workflow` | `stages/implement.md`             |
+| Code review          | `flydocs-workflow` | `stages/review.md`                |
+| QE validation        | `flydocs-workflow` | `stages/validate.md`              |
+| Close issue          | `flydocs-workflow` | `stages/close.md`                 |
+| Start / wrap session | `flydocs-workflow` | `session.md`                      |
+| Knowledge capture    | `flydocs-workflow` | `/knowledge` command              |
+| PR & git workflow    | `flydocs-workflow` | `reference/pr-workflow.md`        |
+| Comment templates    | `flydocs-workflow` | `reference/comment-templates.md`  |
+| Status transitions   | `flydocs-workflow` | `reference/status-workflow.md`    |
+| Priority & estimates | `flydocs-workflow` | `reference/priority-estimates.md` |
+| Issue templates      | `flydocs-workflow` | `templates/`                      |
 
 ## Scripts
 
@@ -50,14 +46,14 @@ All issue, project, workspace, and graph operations use grouped dispatcher
 scripts in `flydocs-workflow/scripts/`. The unified client auto-detects tier
 (cloud vs local) — scripts never check tier directly.
 
-| Dispatcher       | Operations                                                   |
-| ---------------- | ------------------------------------------------------------ |
-| `issues.py`      | create, get, list, transition, assign, update, comment, etc. |
-| `projects.py`    | list-projects, create-project, milestones, cycles            |
-| `workspace.py`   | validate, labels, statuses, teams, config, identity          |
-| `session.py`     | project-update, status-summary                               |
-| `graph_*.py`     | build, query, update, session recording                      |
-| `push/pull_*.py` | Service descriptor sync (cloud tier)                         |
+| Dispatcher       | Operations                                                         |
+| ---------------- | ------------------------------------------------------------------ |
+| `issues.py`      | create, get, list, transition, assign, update, comment, audit, fix |
+| `projects.py`    | list-projects, create-project, milestones, cycles                  |
+| `workspace.py`   | validate, labels, statuses, teams, config, identity                |
+| `session.py`     | project-update, status-summary                                     |
+| `graph_*.py`     | build, query, update, session recording                            |
+| `push/pull_*.py` | Service descriptor sync (cloud tier)                               |
 
 ## Project Context
 
@@ -69,14 +65,14 @@ scripts in `flydocs-workflow/scripts/`. The unified client auto-detects tier
 
 ## Hooks
 
-| Hook                       | Trigger                 | Purpose                              |
-| -------------------------- | ----------------------- | ------------------------------------ |
-| `PreToolUse` (Bash/Edit)   | Before tool execution   | Auto-approve scripts, workflow nudge |
-| `PostToolUse` (Edit/Write) | After code changes      | Auto-format                          |
-| `PostToolUse` (Bash)       | After shell commands    | PR check, transition validation      |
-| `UserPromptSubmit`         | Before prompt           | Inject git/issue/AC context          |
-| `Stop`                     | Agent finishes response | Gate on workflow state               |
-| `SessionStart`             | New session begins      | Inject continuity context            |
+| Hook                       | Trigger                 | Purpose                                                    |
+| -------------------------- | ----------------------- | ---------------------------------------------------------- |
+| `PreToolUse` (Bash/Edit)   | Before tool execution   | Auto-approve scripts, validate create args, comment hints  |
+| `PostToolUse` (Edit/Write) | After code changes      | Auto-format                                                |
+| `PostToolUse` (Bash)       | After shell commands    | Transition validation, session file updates, create audit  |
+| `UserPromptSubmit`         | Before prompt           | Directive workflow context, milestone/label injection      |
+| `Stop`                     | Agent finishes response | Full lifecycle gate (READY, IMPLEMENTING, REVIEW, BLOCKED) |
+| `SessionStart`             | New session begins      | Inject continuity context                                  |
 
 ## Output Formatting
 
@@ -114,8 +110,8 @@ response — session summaries, issue comments, status updates, and plans.
 
 ## Skills Index
 
-Consult the workflow skill when performing **issue operations or status
-transitions**. For general coding tasks, skip this — just write code.
+Consult the workflow skill **before** performing any workflow action. The
+stage files contain required procedures, templates, and field requirements.
 
 | Skill            | Triggers                                                                                                                                                                                                                         | Entry                                    |
 | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |

package/template/.claude/hooks/auto-approve.py

@@ -20,6 +20,24 @@ import os
 import re
 from pathlib import Path
 
+DEBUG_HOOK = os.environ.get('DEBUG_HOOK', '0') == '1'
+SCRIPT_DIR = Path(__file__).parent.resolve()
+DEBUG_LOG = SCRIPT_DIR.parent / 'logs' / 'hook-debug.log'
+
+
+def debug_log(message: str) -> None:
+    """Write debug message to log file if DEBUG_HOOK is enabled."""
+    if not DEBUG_HOOK:
+        return
+    try:
+        DEBUG_LOG.parent.mkdir(parents=True, exist_ok=True)
+        from datetime import datetime
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        with open(DEBUG_LOG, 'a') as f:
+            f.write(f'[{timestamp}] [auto-approve] {message}\n')
+    except (OSError, IOError):
+        pass
+
 
 # Pattern matches the unified flydocs-workflow scripts directory.
 # Uses ^ and $ anchors to prevent injection via command chaining
@@ -44,6 +62,54 @@ def get_script_info(command: str) -> tuple[str, str]:
     return "unknown", "unknown"
 
 
+def validate_create_args(command: str) -> list[str]:
+    """Validate arguments on issues.py create commands.
+
+    Returns a list of warning messages for missing or suspicious arguments.
+    These are advisory — the script itself enforces hard failures.
+    """
+    if 'create' not in command:
+        return []
+
+    warnings = []
+
+    # Check for missing --description (the script will reject, but warn early)
+    if '--description' not in command and '--description-file' not in command:
+        warnings.append(
+            'Missing --description: issues.py create requires a description. '
+            'Read the issue template in .flydocs/templates/ for the expected format.'
+        )
+
+    # Check for suspiciously short descriptions (e.g., --description "")
+    desc_match = re.search(r'--description\s+"([^"]*)"', command)
+    if desc_match and len(desc_match.group(1).strip()) < 20:
+        warnings.append(
+            'Description looks too short. Use the issue template from '
+            '.flydocs/templates/ for structured descriptions with AC checkboxes.'
+        )
+
+    return warnings
+
+
+COMMENT_TEMPLATES: dict[str, str] = {
+    'IMPLEMENTING': 'Comment format: "Starting implementation — [scope/approach description]"',
+    'REVIEW': 'Comment format: "Implementation complete — [what was done, what to verify]"',
+    'COMPLETE': 'Comment format: "All AC verified — [summary of what was delivered]"',
+    'BLOCKED': 'Comment format: "Blocked by [blocker] — [what needs to happen to unblock]"',
+    'CANCELED': 'Comment format: "Canceled — [reason for cancellation]"',
+    'TESTING': 'Comment format: "Ready for QA — [test focus areas]"',
+}
+
+
+def get_transition_comment_hint(command: str) -> str | None:
+    """Inject comment template guidance for transition commands."""
+    match = re.search(r'transition\s+\S+\s+(\S+)', command)
+    if not match:
+        return None
+    target = match.group(1).upper()
+    return COMMENT_TEMPLATES.get(target)
+
+
 def check_workflow_state_for_edit() -> str | None:
     """Check if an active issue needs transition before code changes.
 
@@ -93,15 +159,29 @@ def main():
     tool_name = input_data.get('tool_name', '')
     tool_input = input_data.get('tool_input', {})
 
-    # Auto-approve FlyDocs workflow scripts
+    # Auto-approve FlyDocs workflow scripts (with argument validation)
     if tool_name == 'Bash':
         command = tool_input.get('command', '')
         if should_approve(command):
             skill, script = get_script_info(command)
+
+            # Validate arguments and inject context
+            warnings = validate_create_args(command) if script == 'issues.py' else []
+            transition_hint = get_transition_comment_hint(command) if script == 'issues.py' else None
+
+            context = f"Auto-approved FlyDocs script: {skill}/{script}"
+            if warnings:
+                context += "\nWARNING: " + " | ".join(warnings)
+                debug_log(f"Create validation warnings: {warnings}")
+            if transition_hint:
+                context += f"\n{transition_hint}"
+                debug_log(f"Transition hint: {transition_hint}")
+
+            debug_log(f"Approved: {skill}/{script}")
             result = {
                 "hookSpecificOutput": {
                     "permissionDecision": "allow",
-                    "additionalContext": f"Auto-approved FlyDocs script: {skill}/{script}"
+                    "additionalContext": context
                 }
             }
             print(json.dumps(result))

package/template/.claude/hooks/post-transition-check.py

@@ -2,21 +2,40 @@
 """
 FlyDocs Hook: post-transition-check.py
 Triggered: PostToolUse (Bash)
-Purpose: Validate that issue transitions include comments
+Purpose: Validate transitions and manage session files
 
 Fires after every Bash command. Only acts on `issues.py transition`
-commands. Warns when a transition is missing a comment argument and
-flags unusual state transitions.
+commands. Validates comment presence, flags unusual transitions, and
+updates local session files to keep hooks in sync.
 
 Exit codes:
   0 - Always (non-blocking)
 """
 
 import json
+import os
 import re
 import sys
 from pathlib import Path
 
+DEBUG_HOOK = os.environ.get('DEBUG_HOOK', '0') == '1'
+SCRIPT_DIR = Path(__file__).parent.resolve()
+DEBUG_LOG = SCRIPT_DIR.parent / 'logs' / 'hook-debug.log'
+
+
+def debug_log(message: str) -> None:
+    """Write debug message to log file if DEBUG_HOOK is enabled."""
+    if not DEBUG_HOOK:
+        return
+    try:
+        DEBUG_LOG.parent.mkdir(parents=True, exist_ok=True)
+        from datetime import datetime
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        with open(DEBUG_LOG, 'a') as f:
+            f.write(f'[{timestamp}] [post-transition] {message}\n')
+    except (OSError, IOError):
+        pass
+
 TRANSITION_PATTERN = re.compile(
     r"issues\.py\s+transition\s+(\S+)\s+(\S+)(?:\s+(.+))?"
 )
@@ -39,10 +58,163 @@ def read_current_status() -> str | None:
         return None
 
 
+def post_create_audit(command: str, input_data: dict) -> str | None:
+    """Audit a newly created issue for completeness.
+
+    Checks the command output (tool_result) for the created issue identifier,
+    then verifies the command included expected arguments.
+    """
+    warnings = []
+
+    # Check for description presence in the command
+    if "--description" not in command and "--description-file" not in command:
+        if "--triage" not in command:
+            warnings.append("Created without --description (script should have rejected this)")
+
+    # Check for type
+    if "--type" not in command:
+        warnings.append("Created without --type")
+
+    # Check tool result for success
+    tool_result = input_data.get("tool_result", {})
+    stdout = tool_result.get("stdout", "")
+    if stdout:
+        try:
+            result = json.loads(stdout)
+            identifier = result.get("identifier", "")
+            auto_resolved = result.get("autoResolved", {})
+            if auto_resolved:
+                resolved_parts = [f"{k}={v}" for k, v in auto_resolved.items()]
+                warnings.append(f"Auto-resolved: {', '.join(resolved_parts)}")
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+    # Track compliance score
+    _update_compliance_score(has_findings=len(warnings) > 0, input_data=input_data)
+
+    if not warnings:
+        return None
+    return "Post-create audit: " + " | ".join(warnings)
+
+
+def _update_compliance_score(has_findings: bool, input_data: dict) -> None:
+    """Track per-session compliance score in validation cache.
+
+    Increments total_created and compliant_created counters. Resets
+    when a new session is detected (different session_id).
+    """
+    cwd = input_data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR", "")
+    if not cwd:
+        return
+    cache_file = Path(cwd) / ".flydocs" / "validation-cache.json"
+    try:
+        cache = json.loads(cache_file.read_text()) if cache_file.exists() else {}
+    except (json.JSONDecodeError, OSError):
+        cache = {}
+
+    compliance = cache.get("compliance", {"totalCreated": 0, "compliantCreated": 0})
+    compliance["totalCreated"] = compliance.get("totalCreated", 0) + 1
+    if not has_findings:
+        compliance["compliantCreated"] = compliance.get("compliantCreated", 0) + 1
+    total = compliance["totalCreated"]
+    compliant = compliance["compliantCreated"]
+    compliance["score"] = round(compliant / total * 100) if total > 0 else 100
+    cache["compliance"] = compliance
+
+    try:
+        cache_file.parent.mkdir(parents=True, exist_ok=True)
+        cache_file.write_text(json.dumps(cache, indent=2))
+        debug_log(f"Compliance: {compliant}/{total} = {compliance['score']}%")
+    except OSError:
+        pass
+
+
 def build_output(message: str) -> str:
     return json.dumps({"hookSpecificOutput": {"additionalContext": message}})
 
 
+def update_session_files(ref: str, status: str, input_data: dict) -> None:
+    """Update local session files after a transition.
+
+    Keeps .flydocs/session/ in sync with issue state so that other hooks
+    (stop-gate, prompt-submit) have reliable local state to work with.
+    """
+    # Resolve working directory
+    cwd = input_data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR", "")
+    if cwd and Path(cwd).is_dir():
+        os.chdir(cwd)
+
+    session_dir = Path(".flydocs/session")
+    try:
+        session_dir.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return
+
+    # Always write the new status
+    try:
+        (session_dir / "status").write_text(status)
+    except OSError:
+        pass
+
+    # Update focus file with the issue ref
+    try:
+        focus_file = session_dir / "focus.md"
+        if not focus_file.exists() or ref not in focus_file.read_text():
+            focus_file.write_text(f"# Active Issue\n\n{ref}\n")
+    except OSError:
+        pass
+
+    # On IMPLEMENTING transition, try to cache acceptance criteria
+    if status == "IMPLEMENTING":
+        _cache_acceptance_criteria(ref, session_dir)
+
+    # On COMPLETE or CANCELED, clean up session files
+    if status in ("COMPLETE", "CANCELED"):
+        for f in ("focus.md", "status", "acceptance-criteria.md"):
+            try:
+                (session_dir / f).unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+def _cache_acceptance_criteria(ref: str, session_dir: Path) -> None:
+    """Fetch and cache acceptance criteria from the issue description.
+
+    Extracts checkbox lines from the issue description and writes them
+    to acceptance-criteria.md for local hook use.
+    """
+    try:
+        import subprocess
+        result = subprocess.run(
+            [
+                "python3",
+                ".claude/skills/flydocs-workflow/scripts/issues.py",
+                "get", ref, "--fields", "full",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+        if result.returncode != 0:
+            return
+        issue = json.loads(result.stdout)
+        description = issue.get("description", "")
+        if not description:
+            return
+
+        # Extract checkbox lines
+        ac_lines = [
+            line for line in description.splitlines()
+            if re.match(r"^\s*-\s*\[[ x]\]", line, re.IGNORECASE)
+        ]
+        if ac_lines:
+            (session_dir / "acceptance-criteria.md").write_text(
+                "# Acceptance Criteria\n\n" + "\n".join(ac_lines) + "\n"
+            )
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError, FileNotFoundError):
+        pass
+
+
 def main() -> None:
     try:
         input_data = json.loads(sys.stdin.read())
@@ -55,6 +227,16 @@ def main() -> None:
         sys.exit(0)
 
     command = input_data.get("tool_input", {}).get("command", "")
+
+    # Post-create audit — check if a new issue was created
+    if "issues.py" in command and " create " in command:
+        audit_msg = post_create_audit(command, input_data)
+        if audit_msg:
+            print(build_output(audit_msg))
+        else:
+            print("{}")
+        sys.exit(0)
+
     match = TRANSITION_PATTERN.search(command)
 
     if not match:
@@ -84,8 +266,13 @@ def main() -> None:
                 f"Verify this is intentional."
             )
             print(build_output(msg))
+            # Still update session files even for unusual transitions
+            update_session_files(ref, status, input_data)
             sys.exit(0)
 
+    # Update session files after successful transition
+    update_session_files(ref, status, input_data)
+
     print("{}")
     sys.exit(0)
 

package/template/.claude/hooks/prompt-submit.py

@@ -149,13 +149,15 @@ def get_issue_context_line() -> str | None:
         except (OSError, IOError):
             pass
 
-    # Workflow nudge based on status
+    # Directive workflow instructions based on status
     if status == 'READY':
-        parts.append('[Transition to In Progress before starting work]')
+        parts.append('[REQUIRED: Read stages/activate.md then transition to IMPLEMENTING before writing code]')
     elif status == 'IMPLEMENTING':
-        parts.append('[Update AC as you go, transition to Review when done]')
+        parts.append('[REQUIRED: Update AC checkboxes in issue description as you complete them. Transition to REVIEW when done]')
     elif status == 'REVIEW':
-        parts.append('[Verify AC before approving]')
+        parts.append('[REQUIRED: Verify all AC checkboxes are checked before approving]')
+    elif status == 'BLOCKED':
+        parts.append('[Issue is BLOCKED — resolve blocker or transition back to IMPLEMENTING]')
 
     return f'Issue: {" | ".join(parts)}'
 
@@ -178,14 +180,26 @@ def get_ac_progress() -> str | None:
     return None
 
 
-def get_workflow_reminder(status: str) -> str | None:
-    """Get workflow reminder based on current status."""
-    reminders = {
-        'IMPLEMENTING': '[Reminder: Log progress with comments, run tests before REVIEW]',
-        'REVIEW': '[Reminder: Check acceptance criteria before approving]',
-        'TESTING': '[Reminder: Validate all AC met before marking COMPLETE]'
+def get_workflow_directive(status: str | None, has_issue: bool) -> str | None:
+    """Get directive workflow instruction based on current state.
+
+    These are not reminders — they are required actions the agent must follow.
+    """
+    if not has_issue:
+        return '[No active issue. Run /activate to pick an issue or /capture to create one before writing code]'
+
+    if not status:
+        return None
+
+    directives = {
+        'BACKLOG': '[REQUIRED: Read stages/activate.md. Transition to READY or IMPLEMENTING before starting work]',
+        'READY': '[REQUIRED: Read stages/activate.md. Transition to IMPLEMENTING before writing code]',
+        'IMPLEMENTING': '[REQUIRED: Update AC checkboxes in issue description. Add progress comments for milestones. Transition to REVIEW when implementation is complete]',
+        'REVIEW': '[REQUIRED: Verify ALL acceptance criteria are checked. Read stages/review.md for the full review procedure]',
+        'TESTING': '[REQUIRED: Validate all AC met. Read stages/validate.md before marking COMPLETE]',
+        'BLOCKED': '[Issue is BLOCKED. Resolve the blocker or escalate. Transition back to IMPLEMENTING when unblocked]',
     }
-    return reminders.get(status)
+    return directives.get(status)
 
 
 def get_orientation_context() -> str | None:
@@ -446,8 +460,9 @@ def main() -> None:
         if branch_match:
             branch = branch_match.group(1).rstrip(',')
 
-    # Active project context
+    # Active project + milestone + label config context
     config_file = Path('.flydocs/config.json')
+    cfg = None
     if config_file.exists():
         try:
             cfg = json.loads(config_file.read_text())
@@ -456,6 +471,18 @@ def main() -> None:
                 context_parts.append(f'ActiveProject: {active_projects[0]}')
             elif cfg.get('tier') == 'cloud' and cfg.get('setupComplete'):
                 context_parts.append('[No active project set — run workspace.py set-active-project]')
+
+            # Milestone ID — so agent can pass --milestone if needed
+            milestone_id = cfg.get('workspace', {}).get('defaultMilestoneId')
+            if milestone_id:
+                context_parts.append(f'Milestone: {milestone_id}')
+
+            # Label mapping — compact type->ID for issue creation
+            category_labels = cfg.get('issueLabels', {}).get('category', {})
+            configured = {k: v for k, v in category_labels.items() if v}
+            if configured:
+                mapping = ','.join(f'{k}={v[:8]}' for k, v in configured.items())
+                context_parts.append(f'Labels: {mapping}')
         except (json.JSONDecodeError, OSError, IOError):
             pass
 
@@ -499,6 +526,20 @@ def main() -> None:
         debug_log(f'Outputting plain text context: {context}')
         print(context)
 
+    # Workflow directive — tells the agent what it MUST do based on current state
+    issue_id, status = get_issue_context()
+    directive = get_workflow_directive(status, has_issue=issue_id is not None)
+    if directive:
+        debug_log(f'Workflow directive: {directive}')
+        print(directive)
+
+    # Capture directive — when the prompt looks like issue creation
+    if prompt and not issue_id:
+        prompt_lower = prompt.lower()
+        capture_signals = ['capture', 'log a bug', 'new issue', 'add to backlog', 'found a bug', 'new idea', 'quick capture']
+        if any(signal in prompt_lower for signal in capture_signals):
+            print('[REQUIRED: Read stages/capture.md for the full capture procedure including templates and label config]')
+
     # Orientation context (lightweight file reads, no subprocess)
     orientation = get_orientation_context()
     if orientation: