@techierathore/techieflow 1.0.2 → 1.0.3

package/.tfcore/tasks/kb-mode-interaction.md

@@ -1,75 +0,0 @@
-# KB Mode Interaction Task
-
-## Purpose
-
-Provide a user-friendly interface to the TechieFlow knowledge base without overwhelming users with information upfront.
-
-## Instructions
-
-When entering KB mode (\*kb-mode), follow these steps:
-
-### 1. Welcome and Guide
-
-Announce entering KB mode with a brief, friendly introduction.
-
-### 2. Present Topic Areas
-
-Offer a concise list of main topic areas the user might want to explore:
-
-**What would you like to know more about?**
-
-1. **Setup & Installation** - Getting started with TechieFlow
-2. **Workflows** - Choosing the right workflow for your project
-3. **Web vs IDE** - When to use each environment
-4. **Agents** - Understanding specialized agents and their roles
-5. **Documents** - PRDs, Architecture, Stories, and more
-6. **Agile Process** - How TechieFlow implements Agile methodologies
-7. **Configuration** - Customizing TechieFlow for your needs
-8. **Best Practices** - Tips for effective TechieFlow usage
-
-Or ask me about anything else related to TechieFlow!
-
-### 3. Respond Contextually
-
-- Wait for user's specific question or topic selection
-- Provide focused, relevant information from the knowledge base
-- Offer to dive deeper or explore related topics
-- Keep responses concise unless user asks for detailed explanations
-
-### 4. Interactive Exploration
-
-- After answering, suggest related topics they might find helpful
-- Maintain conversational flow rather than data dumping
-- Use examples when appropriate
-- Reference specific documentation sections when relevant
-
-### 5. Exit Gracefully
-
-When user is done or wants to exit KB mode:
-
-- Summarize key points discussed if helpful
-- Remind them they can return to KB mode anytime with \*kb-mode
-- Suggest next steps based on what was discussed
-
-## Example Interaction
-
-**User**: \*kb-mode
-
-**Assistant**: I've entered KB mode and have access to the full TechieFlow knowledge base. I can help you with detailed information about any aspect of TechieFlow.
-
-**What would you like to know more about?**
-
-1. **Setup & Installation** - Getting started with TechieFlow
-2. **Workflows** - Choosing the right workflow for your project
-3. **Web vs IDE** - When to use each environment
-4. **Agents** - Understanding specialized agents and their roles
-5. **Documents** - PRDs, Architecture, Stories, and more
-6. **Agile Process** - How TechieFlow implements Agile methodologies
-7. **Configuration** - Customizing TechieFlow for your needs
-8. **Best Practices** - Tips for effective TechieFlow usage
-
-Or ask me about anything else related to TechieFlow!
-
-**User**: Tell me about workflows
-
-**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]

package/.tfcore/tasks/shard-doc.md

@@ -1,185 +0,0 @@
-# Document Sharding Task
-
-## Purpose
-
-- Split a large document into multiple smaller documents based on level 2 sections
-- Create a folder structure to organize the sharded documents
-- Maintain all content integrity including code blocks, diagrams, and markdown formatting
-
-## Primary Method: Automatic with markdown-tree
-
-[[LLM: First, check if markdownExploder is set to true in .tfcore/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
-
-If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
-
-If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
-
-1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
-2. Or set markdownExploder to false in .tfcore/core-config.yaml
-
-**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
-
-If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
-
-1. Set markdownExploder to true in .tfcore/core-config.yaml
-2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
-
-I will now proceed with the manual sharding process."
-
-Then proceed with the manual method below ONLY if markdownExploder is false.]]
-
-### Installation and Usage
-
-1. **Install globally**:
-
-   ```bash
-   npm install -g @kayvan/markdown-tree-parser
-   ```
-
-2. **Use the explode command**:
-
-   ```bash
-   # For PRD
-   md-tree explode docs/prd.md docs/prd
-
-   # For Architecture
-   md-tree explode docs/architecture.md docs/architecture
-
-   # For any document
-   md-tree explode [source-document] [destination-folder]
-   ```
-
-3. **What it does**:
-   - Automatically splits the document by level 2 sections
-   - Creates properly named files
-   - Adjusts heading levels appropriately
-   - Handles all edge cases with code blocks and special markdown
-
-If the user has @kayvan/markdown-tree-parser installed, use it and skip the manual process below.
-
----
-
-## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
-
-### Task Instructions
-
-1. Identify Document and Target Location
-
-- Determine which document to shard (user-provided path)
-- Create a new folder under `docs/` with the same name as the document (without extension)
-- Example: `docs/prd.md` → create folder `docs/prd/`
-
-2. Parse and Extract Sections
-
-CRITICAL AEGNT SHARDING RULES:
-
-1. Read the entire document content
-2. Identify all level 2 sections (## headings)
-3. For each level 2 section:
-   - Extract the section heading and ALL content until the next level 2 section
-   - Include all subsections, code blocks, diagrams, lists, tables, etc.
-   - Be extremely careful with:
-     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
-     - Mermaid diagrams - preserve the complete diagram syntax
-     - Nested markdown elements
-     - Multi-line content that might contain ## inside code blocks
-
-CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]]
-
-### 3. Create Individual Files
-
-For each extracted section:
-
-1. **Generate filename**: Convert the section heading to lowercase-dash-case
-   - Remove special characters
-   - Replace spaces with dashes
-   - Example: "## Tech Stack" → `tech-stack.md`
-
-2. **Adjust heading levels**:
-   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
-   - All subsection levels decrease by 1:
-
-   ```txt
-     - ### → ##
-     - #### → ###
-     - ##### → ####
-     - etc.
-   ```
-
-3. **Write content**: Save the adjusted content to the new file
-
-### 4. Create Index File
-
-Create an `index.md` file in the sharded folder that:
-
-1. Contains the original level 1 heading and any content before the first level 2 section
-2. Lists all the sharded files with links:
-
-```markdown
-# Original Document Title
-
-[Original introduction content if any]
-
-## Sections
-
-- [Section Name 1](./section-name-1.md)
-- [Section Name 2](./section-name-2.md)
-- [Section Name 3](./section-name-3.md)
-  ...
-```
-
-### 5. Preserve Special Content
-
-1. **Code blocks**: Must capture complete blocks including:
-
-   ```language
-   content
-   ```
-
-2. **Mermaid diagrams**: Preserve complete syntax:
-
-   ```mermaid
-   graph TD
-   ...
-   ```
-
-3. **Tables**: Maintain proper markdown table formatting
-
-4. **Lists**: Preserve indentation and nesting
-
-5. **Inline code**: Preserve backticks
-
-6. **Links and references**: Keep all markdown links intact
-
-7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
-
-### 6. Validation
-
-After sharding:
-
-1. Verify all sections were extracted
-2. Check that no content was lost
-3. Ensure heading levels were properly adjusted
-4. Confirm all files were created successfully
-
-### 7. Report Results
-
-Provide a summary:
-
-```text
-Document sharded successfully:
-- Source: [original document path]
-- Destination: docs/[folder-name]/
-- Files created: [count]
-- Sections:
-  - section-name-1.md: "Section Title 1"
-  - section-name-2.md: "Section Title 2"
-  ...
-```
-
-## Important Notes
-
-- Never modify the actual content, only adjust heading levels
-- Preserve ALL formatting, including whitespace where significant
-- Handle edge cases like sections with code blocks containing ## symbols
-- Ensure the sharding is reversible (could reconstruct the original from shards)

package/.tfcore/utils/tf-codex-bind.py

@@ -1,196 +0,0 @@
-#!/usr/bin/env python3
-"""Generate TechieFlow's Codex agents and thin workflow skills."""
-
-from __future__ import annotations
-
-import argparse
-import pathlib
-import re
-
-
-PHASES = {
-    "day1-brownfield": ("analyst", "Reverse-document and initialize an existing application."),
-    "day1-greenfield": ("analyst", "Initialize planning artifacts and mockups for a new application."),
-    "amend-docs": ("analyst", "Amend existing requirements and design artifacts in place."),
-    "author-brd": ("analyst", "Interactively author or extend numbered business requirements."),
-    "mockups": ("analyst", "Create or update the greenfield UI design and HTML mockups."),
-    "split-brd": ("analyst", "Convert a BRD into the single implementation checklist."),
-    "build-phase": ("flow_master", "Implement the open checklist and chain smoke and verification."),
-    "verify-phase": ("verifier", "Independently verify requirements against runtime evidence."),
-    "fix-issues": ("flow_master", "Fix reported or verifier-discovered application defects."),
-    "triage-issues": ("flow_master", "Analyze and document human-found bugs without fixing source."),
-    "log-miss": ("flow_master", "Record one missed requirement as telemetry and a checklist line."),
-    "devguide": ("flow_master", "Create the developer-facing screen and component guide."),
-    "productguide": ("flow_master", "Create the user-facing guide from the running application."),
-    "handoff-phase": ("flow_master", "Complete handoff documents, status, and rendered artifacts."),
-    "refresh-status": ("flow_master", "Recover truthful project status after an interrupted run."),
-    "generate-html": ("flow_master", "Render an arbitrary human-readable Markdown document to HTML."),
-    "render-workflow-docs": ("flow_master", "Render the canonical BRD, Architecture, and status HTML files."),
-    "metrics-report": ("flow_master", "Report TechieFlow development telemetry without changing code."),
-}
-
-PERSONAS = {
-    "flow-master": "flow-master.md",
-    "analyst": "analyst.md",
-    "architect": "architect.md",
-    "verifier": "verifier.md",
-}
-
-WORKERS = {
-    "tf-builder": """Implement one assigned FN/NFR requirement cluster. Read `.tfcore/tasks/_smoke-test-policy.md`. Never run git or gh. Follow project coding standards, smoke the changed behavior, update only the assigned checklist rows, and return structured evidence to the parent.""",
-    "tf-test-writer": """Write black-box verification tests for one assigned requirement cluster. Never edit application source and never run git or gh. Follow `.tfcore/tasks/verify-phase.md` and return tests added, tests refreshed, and anything unobservable.""",
-    "tf-explorer": """Perform a focused read-only codebase scan. Never edit files and never run git or gh. Return concise evidence with file paths and symbols.""",
-    "trblazeui": """Read the NuGet-deployed TrBlazeUI persona and adopt its implementation rules. Resolve it in this order and use the FIRST that exists: `.claude/commands/trblazeui.md` (current deploy target), `.claude/trblazeui.md` (legacy deploy target), `.opencode/command/trblazeui.md`, `.trblazeui/TrBlazeUI-AI-Reference.md` (packaged component reference). Only if NONE exists, report that the TrBlazeUI persona is not deployed (`dotnet build` the app to unpack the package) and stop. Never run git or gh.""",
-    "techierag": """Read the NuGet-deployed TechieRag persona and adopt its implementation rules. Resolve it in this order and use the FIRST that exists: `.claude/commands/techierag.md` (current deploy target), `.claude/techierag.md` (legacy deploy target), `.opencode/command/techierag.md`, `.techierag/TechieRag-AI-Reference.md` (packaged service reference). Only if NONE exists, report that the TechieRag persona is not deployed (`dotnet build` the app to unpack the package) and stop. Never run git or gh.""",
-}
-
-# Library-persona workers are COMPATIBILITY wrappers: the library NuGet packages own
-# the native `.codex/agents/<lib>.toml` (TrBlazeUI.Components >= 2.0.3 deploys it on
-# `dotnet build`; TechieRag is expected to follow the same contract). The package's
-# MSBuild target deploys only when the file is absent OR the ownership marker
-# `.<lib>/.codex-agent-package-owned` exists; otherwise it preserves what it finds as
-# consumer-owned. So the framework must (a) never overwrite a file that is not its own
-# wrapper, and (b) write the marker alongside its wrapper so the package is allowed to
-# replace it. The wrapper then self-retires per repo on the first post-2.0.3 build.
-COMPAT = {
-    "trblazeui": ("TrBlazeUI.Components", ".trblazeui"),
-    "techierag": ("TechieRag", ".techierag"),
-}
-MARKER = ".codex-agent-package-owned"
-
-
-def own_wrapper(path: pathlib.Path, name: str) -> bool:
-    """True when `path` is absent or holds the framework's own compat wrapper."""
-    if not path.exists():
-        return True
-    return f'description = "TechieFlow {name} role."' in path.read_text(encoding="utf-8")
-
-
-def routing(path: pathlib.Path) -> dict:
-    cfg = {"enabled": False, "tiers": {}, "phases": {}, "subagents": {}, "effort": {}}
-    section = tier = None
-    if not path.exists():
-        return cfg
-    for line in path.read_text(encoding="utf-8").splitlines():
-        if not line.strip() or line.lstrip().startswith("#"):
-            continue
-        if not line.startswith(" "):
-            key, _, value = line.partition(":")
-            section, tier = key.strip(), None
-            if section == "enabled":
-                cfg["enabled"] = value.strip() == "true"
-        elif section == "tiers":
-            if re.match(r"^  [a-z-]+:\s*$", line):
-                tier = line.strip()[:-1]
-                cfg["tiers"][tier] = {}
-            elif tier and line.startswith("    "):
-                key, _, value = line.strip().partition(":")
-                cfg["tiers"][tier][key] = value.strip()
-        elif section in ("phases", "subagents", "effort"):
-            key, _, value = line.strip().partition(":")
-            cfg[section][key] = value.strip()
-    return cfg
-
-
-def quoted(value: str) -> str:
-    return '"' + value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n") + '"'
-
-
-def write(path: pathlib.Path, content: str) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(content.rstrip() + "\n", encoding="utf-8", newline="\n")
-
-
-def persona_instructions(root: pathlib.Path, source_name: str) -> str:
-    source = root / ".tfcore" / "agents" / source_name
-    return f"""Read `{source.relative_to(root)}` completely before acting and follow its persona, core principles, command routing, and dependency rules. Skip only its activation greeting/help/halt ritual because this is a spawned Codex role. Treat `.tfcore/tasks/*.md` as executable workflows. Never run git or gh. Preserve TechieFlow's smoke, verifier, artifact-location, local-only runtime, checklist, and PROJECT-STATUS invariants. Load only dependencies needed for the assigned task."""
-
-
-def agent_file(name: str, description: str, instructions: str, model: str | None,
-               effort: str | None, read_only: bool = False) -> str:
-    lines = [f"name = {quoted(name)}", f"description = {quoted(description)}",
-             f"developer_instructions = {quoted(instructions)}"]
-    if model:
-        lines.append(f"model = {quoted(model)}")
-    if effort:
-        lines.append(f"model_reasoning_effort = {quoted(effort)}")
-    if read_only:
-        lines.append('sandbox_mode = "read-only"')
-    return "\n".join(lines)
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("root", nargs="?", default=".")
-    args = parser.parse_args()
-    root = pathlib.Path(args.root).resolve()
-    if not (root / ".tfcore").is_dir():
-        parser.error(f"not a TechieFlow repository: {root}")
-    cfg = routing(root / ".tfcore" / "routing.yaml")
-
-    persona_tier = {"flow-master": "build-phase", "analyst": "day1-greenfield",
-                    "architect": "day1-greenfield", "verifier": "verify-phase"}
-    for name, source in PERSONAS.items():
-        tier = cfg["phases"].get(persona_tier[name], "inherit")
-        model = cfg["tiers"].get(tier, {}).get("codex") if cfg["enabled"] and tier != "inherit" else None
-        effort = cfg["effort"].get(tier) if model else None
-        write(root / ".codex" / "agents" / f"{name}.toml", agent_file(
-            name.replace("-", "_"), f"TechieFlow {name} specialist.",
-            persona_instructions(root, source), model, effort))
-
-    kept = []
-    for name, instructions in WORKERS.items():
-        tier = cfg["subagents"].get(name, "inherit")
-        model = cfg["tiers"].get(tier, {}).get("codex") if cfg["enabled"] and tier != "inherit" else None
-        effort = cfg["effort"].get(tier) if model else None
-        target = root / ".codex" / "agents" / f"{name}.toml"
-        if name in COMPAT:
-            package, lib_dir = COMPAT[name]
-            if not own_wrapper(target, name):
-                kept.append(name)  # package- or consumer-owned agent: never overwrite
-                continue
-            marker = root / lib_dir / MARKER
-            if not marker.exists():
-                write(marker, package)
-            ignore = root / lib_dir / ".gitignore"  # same `*` the package writes on build
-            if not ignore.exists():
-                write(ignore, "*")
-        write(target, agent_file(
-            name.replace("-", "_"), f"TechieFlow {name} role.", instructions,
-            model, effort, read_only=name == "tf-explorer"))
-
-    for phase, (owner, description) in PHASES.items():
-        skill_name = f"techieflow-{phase.removesuffix('-phase')}"
-        task = f".tfcore/tasks/{phase}.md"
-        body = f"""---
-name: {skill_name}
-description: {description} Use when a TechieFlow project needs its `{phase}` workflow.
----
-
-# {skill_name}
-
-1. Read `{task}` completely and follow it as the canonical executable workflow.
-2. Read `.tfcore/core-config.yaml` and only the task dependencies required for this run.
-3. Operate as the `{owner}` role. Delegate only where the task explicitly calls for independent subagents, using the registered Codex roles and waiting for their results.
-4. Preserve interactive elicitation unless `.tfcore/.session/yolo.json` exists or the user explicitly requested YOLO/goal mode.
-5. Never run `git` or `gh`. Run required builds, smoke tests, runtime observations, verifier gates, document updates, and telemetry yourself.
-6. Treat old `*...` and harness slash-command text in the canonical task as vocabulary aliases; execute the named task or delegate to the named Codex role directly.
-"""
-        write(root / ".agents" / "skills" / skill_name / "SKILL.md", body)
-
-    yolo = """---
-name: techieflow-yolo
-description: Enable, disable, or inspect TechieFlow YOLO mode for an explicitly requested unattended workflow.
----
-
-Read `.tfcore/tasks/_yolo-mode.md` completely. Run `bash .tfcore/utils/tf-yolo.sh on|off` as requested. YOLO removes elicitation pauses but does not broaden the user's task, allow git/gh, bypass the Codex workspace sandbox, or waive genuine external blockers. For a supervised long-running goal, use `.tfcore/utils/tf-goal.sh --harness codex`.
-"""
-    write(root / ".agents" / "skills" / "techieflow-yolo" / "SKILL.md", yolo)
-    print(f"tf-codex-bind: generated {len(PERSONAS) + len(WORKERS) - len(kept)} agents and {len(PHASES) + 1} skills")
-    for name in kept:
-        print(f"tf-codex-bind: kept library-owned .codex/agents/{name}.toml (compat wrapper retired)")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/.tfcore/utils/tf-codex-telemetry.py

@@ -1,60 +0,0 @@
-#!/usr/bin/env python3
-"""Emit authoritative Codex exec JSONL usage into TechieFlow sessions telemetry."""
-
-from __future__ import annotations
-
-import json
-import os
-import pathlib
-import subprocess
-import sys
-
-
-def main() -> int:
-    if len(sys.argv) != 3:
-        print("usage: tf-codex-telemetry.py <project-root> <codex-jsonl>", file=sys.stderr)
-        return 2
-    root = pathlib.Path(sys.argv[1]).resolve()
-    source = pathlib.Path(sys.argv[2])
-    thread_id = None
-    model = None
-    totals = {"input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0,
-              "reasoning_output_tokens": 0}
-    try:
-        for line in source.read_text(encoding="utf-8", errors="replace").splitlines():
-            try:
-                event = json.loads(line)
-            except Exception:
-                continue
-            if event.get("type") == "thread.started":
-                thread_id = event.get("thread_id") or thread_id
-            if event.get("model"):
-                model = event.get("model")
-            if event.get("type") == "turn.completed" and isinstance(event.get("usage"), dict):
-                usage = event["usage"]
-                totals["input_tokens"] += int(usage.get("input_tokens") or 0)
-                totals["output_tokens"] += int(usage.get("output_tokens") or 0)
-                totals["cache_read_tokens"] += int(usage.get("cached_input_tokens") or 0)
-                totals["reasoning_output_tokens"] += int(usage.get("reasoning_output_tokens") or 0)
-    except Exception:
-        return 0
-    if not thread_id or not any(totals.values()):
-        return 0
-    record = {
-        "kind": "session", "session_id": thread_id, "model": model,
-        "duration_s": None, **totals, "cache_creation_tokens": None,
-        "cost_usd": None, "children_sessions": None,
-    }
-    emit = root / ".tfcore" / "utils" / "tf-emit.sh"
-    env = os.environ.copy()
-    env.update(TF_HARNESS="codex", TF_PROJECT_DIR=str(root), CLAUDE_PROJECT_DIR=str(root))
-    try:
-        subprocess.run(["bash", str(emit), "sessions"], input=json.dumps(record), text=True,
-                       timeout=10, env=env, check=False)
-    except Exception:
-        pass
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())