@techierathore/techieflow 1.0.2 → 1.0.4

package/.tfcore/utils/techieflow-doc-template.md

@@ -1,325 +0,0 @@
-# TechieFlow Document Template Specification
-
-## Overview
-
-TechieFlow document templates are defined in YAML format to drive interactive document generation and agent interaction. Templates separate structure definition from content generation, making them both human and LLM-agent-friendly.
-
-## Template Structure
-
-```yaml
-template:
-  id: template-identifier
-  name: Human Readable Template Name
-  version: 1.0
-  output:
-    format: markdown
-    filename: default-path/to/{{filename}}.md
-    title: '{{variable}} Document Title'
-
-workflow:
-  mode: interactive
-  elicitation: advanced-elicitation
-
-sections:
-  - id: section-id
-    title: Section Title
-    instruction: |
-      Detailed instructions for the LLM on how to handle this section
-    # ... additional section properties
-```
-
-## Core Fields
-
-### Template Metadata
-
-- **id**: Unique identifier for the template
-- **name**: Human-readable name displayed in UI
-- **version**: Template version for tracking changes
-- **output.format**: Default "markdown" for document templates
-- **output.filename**: Default output file path (can include variables)
-- **output.title**: Document title (becomes H1 in markdown)
-
-### Workflow Configuration
-
-- **workflow.mode**: Default interaction mode ("interactive" or "yolo")
-- **workflow.elicitation**: Elicitation task to use ("advanced-elicitation")
-
-## Section Properties
-
-### Required Fields
-
-- **id**: Unique section identifier
-- **title**: Section heading text
-- **instruction**: Detailed guidance for LLM on handling this section
-
-### Optional Fields
-
-#### Content Control
-
-- **type**: Content type hint for structured sections
-- **template**: Fixed template text for section content
-- **item_template**: Template for repeatable items within section
-- **prefix**: Prefix for numbered items (e.g., "FR", "NFR")
-
-#### Behavior Flags
-
-- **elicit**: Boolean - Apply elicitation after section rendered
-- **repeatable**: Boolean - Section can be repeated multiple times
-- **condition**: String - Condition for including section (e.g., "has ui requirements")
-
-#### Agent Permissions
-
-- **owner**: String - Agent role that initially creates/populates this section
-- **editors**: Array - List of agent roles allowed to modify this section
-- **readonly**: Boolean - Section cannot be modified after initial creation
-
-#### Content Guidance
-
-- **examples**: Array of example content (not included in output)
-- **choices**: Object with choice options for common decisions
-- **placeholder**: Default placeholder text
-
-#### Structure
-
-- **sections**: Array of nested child sections
-
-## Supported Types
-
-### Content Types
-
-- **bullet-list**: Unordered list items
-- **numbered-list**: Ordered list with optional prefix
-- **paragraphs**: Free-form paragraph text
-- **table**: Structured table data
-- **code-block**: Code or configuration blocks
-- **template-text**: Fixed template with variable substitution
-- **mermaid**: Mermaid diagram with specified type and details
-
-### Special Types
-
-- **repeatable-container**: Container for multiple instances
-- **conditional-block**: Content shown based on conditions
-- **choice-selector**: Present choices to user
-
-## Advanced Features
-
-### Variable Substitution
-
-Use `{{variable_name}}` in titles, templates, and content:
-
-```yaml
-title: 'Epic {{epic_number}} {{epic_title}}'
-template: 'As a {{user_type}}, I want {{action}}, so that {{benefit}}.'
-```
-
-### Conditional Sections
-
-```yaml
-- id: ui-section
-  title: User Interface Design
-  condition: Project has UX/UI Requirements
-  instruction: Only include if project has UI components
-```
-
-### Choice Integration
-
-```yaml
-choices:
-  architecture: [Monolith, Microservices, Serverless]
-  testing: [Unit Only, Unit + Integration, Full Pyramid]
-```
-
-### Mermaid Diagrams
-
-```yaml
-- id: system-architecture
-  title: System Architecture Diagram
-  type: mermaid
-  instruction: Create a system architecture diagram showing key components and data flow
-  mermaid_type: flowchart
-  details: |
-    Show the following components:
-    - User interface layer
-    - API gateway
-    - Core services
-    - Database layer
-    - External integrations
-```
-
-**Supported mermaid_type values:**
-
-**Core Diagram Types:**
-
-- `flowchart` - Flow charts and process diagrams
-- `sequenceDiagram` - Sequence diagrams for interactions
-- `classDiagram` - Class relationship diagrams (UML)
-- `stateDiagram` - State transition diagrams
-- `erDiagram` - Entity relationship diagrams
-- `gantt` - Gantt charts for timelines
-- `pie` - Pie charts for data visualization
-
-**Advanced Diagram Types:**
-
-- `journey` - User journey maps
-- `mindmap` - Mindmaps for brainstorming
-- `timeline` - Timeline diagrams for chronological events
-- `quadrantChart` - Quadrant charts for data categorization
-- `xyChart` - XY charts (bar charts, line charts)
-- `sankey` - Sankey diagrams for flow visualization
-
-**Specialized Types:**
-
-- `c4Context` - C4 context diagrams (experimental)
-- `requirement` - Requirement diagrams
-- `packet` - Network packet diagrams
-- `block` - Block diagrams
-- `kanban` - Kanban boards
-
-### Agent Permissions Example
-
-```yaml
-- id: story-details
-  title: Story
-  owner: scrum-master
-  editors: [scrum-master]
-  readonly: false
-  sections:
-    - id: dev-notes
-      title: Dev Notes
-      owner: dev-agent
-      editors: [dev-agent]
-      readonly: false
-      instruction: Implementation notes and technical details
-    - id: qa-results
-      title: QA Results
-      owner: qa-agent
-      editors: [qa-agent]
-      readonly: true
-      instruction: Quality assurance test results
-```
-
-### Repeatable Sections
-
-```yaml
-- id: epic-details
-  title: Epic {{epic_number}} {{epic_title}}
-  repeatable: true
-  sections:
-    - id: story
-      title: Story {{epic_number}}.{{story_number}} {{story_title}}
-      repeatable: true
-      sections:
-        - id: criteria
-          title: Acceptance Criteria
-          type: numbered-list
-          item_template: '{{criterion_number}}: {{criteria}}'
-          repeatable: true
-```
-
-### Examples with Code Blocks
-
-````yaml
-examples:
-  - 'FR6: The system must authenticate users within 2 seconds'
-  - |
-    ```mermaid
-    sequenceDiagram
-        participant User
-        participant API
-        participant DB
-        User->>API: POST /login
-        API->>DB: Validate credentials
-        DB-->>API: User data
-        API-->>User: JWT token
-    ```
-  - |
-    **Architecture Decision Record**
-
-    **Decision**: Use PostgreSQL for primary database
-    **Rationale**: ACID compliance and JSON support needed
-    **Consequences**: Requires database management expertise
-````
-
-## Section Hierarchy
-
-Templates define the complete document structure starting with the first H2 - each level in is the next H#:
-
-```yaml
-sections:
-  - id: overview
-    title: Project Overview
-    sections:
-      - id: goals
-        title: Goals
-      - id: scope
-        title: Scope
-        sections:
-          - id: in-scope
-            title: In Scope
-          - id: out-scope
-            title: Out of Scope
-```
-
-## Processing Flow
-
-1. **Parse Template**: Load and validate YAML structure
-2. **Initialize Workflow**: Set interaction mode and elicitation
-3. **Process Sections**: Handle each section in order:
-   - Check conditions
-   - Apply instructions
-   - Generate content
-   - Handle choices and variables
-   - Apply elicitation if specified
-   - Process nested sections
-4. **Generate Output**: Create clean markdown document
-
-## Best Practices
-
-### Template Design
-
-- Keep instructions clear and specific
-- Use examples for complex content
-- Structure sections logically
-- Include all necessary guidance for LLM
-
-### Content Instructions
-
-- Be explicit about expected format
-- Include reasoning for decisions
-- Specify interaction patterns
-- Reference other documents when needed
-
-### Variable Naming
-
-- Use descriptive variable names
-- Follow consistent naming conventions
-- Document expected variable values
-
-### Examples Usage
-
-- Provide concrete examples for complex sections
-- Include both simple and complex cases
-- Use realistic project scenarios
-- Include code blocks and diagrams when helpful
-
-## Validation
-
-Templates should be validated for:
-
-- Valid YAML syntax
-- Required fields present
-- Consistent section IDs
-- Proper nesting structure
-- Valid variable references
-
-## Migration from Legacy
-
-When converting from markdown+frontmatter templates:
-
-1. Extract embedded `[[LLM:]]` instructions to `instruction` fields
-2. Convert `<<REPEAT>>` blocks to `repeatable: true` sections
-3. Extract `^^CONDITIONS^^` to `condition` fields
-4. Move `@{examples}` to `examples` arrays
-5. Convert `{{placeholders}}` to proper variable syntax
-
-This specification ensures templates are both human-readable and machine-processable while maintaining the flexibility needed for complex document generation.

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())