🧭 frontier-axi

September 13, 2026 · View on GitHub

The Pre-Flight Cognitive Bridge for Agentic SDLC & Upstream Frontier Tracking

Bridging the gap between nascent human ideation (/ask-matt) and deterministic task execution (tasks-axi).

🎯 1. The Problem: The Vague Ticket Paradox (Neden Böyle Bir Şey Yaptık?)

In modern AI-native software engineering, work is split between creative human intent and deterministic agent execution:

The Guardrail (tasks-axi Rule #5):

"No Ephemeral or Vague Tickets: Every ticket created in tasks-axi MUST include verifiable Acceptance Criteria and What to build."
The Reality of Software Ideation: When embarking on a new project or large feature, requirements start broad, ambiguous, and fuzzy. Architectural decisions (horizontal seams vs. vertical tracer bullets) are not yet settled.
The Paradox:
- Premature Ticket Creation: If you dump vague ideas directly into tasks-axi, unsupervised implementer agents hallucinate, write irrelevant unit tests, and wander off track.
- Chat Memory Trap: If you leave fuzzy ideas only in ephemeral chat conversation, context compaction (/compact) or session resets wipe them out. You lose the why behind your architectural thinking.

frontier-axi resolves this paradox: It is the upstream staging lounge for cognitive state. It gives ambiguous ideas, open architectural inquiries, and unresolved questions a persistent, deterministic home before they are ready for code execution.

🧠 2. Philosophy & Primary References

frontier-axi is synthesized from two foundational engineering philosophies:

🏛️ Matt Pocock's Cognitive Domain Craft (`/ask-matt` & `/grilling`)

The Design Tree & The Frontier: Every idea branches into sub-decisions. The frontier is the exact set of questions whose prerequisites are settled and need human answers.
Role Division: "Finding facts is the agent's job; decisions are the user's." An agent must never guess or silently assume architectural decisions.
Definition of Ready: Work only transitions to code when the frontier is empty, the highest test seam is agreed upon, and tracer-bullet vertical slices are defined.

⚡ Kun Chen's L8 Systems Engineering & AXI Paradigm (`kunchenguid/axi`)

Built on axi-sdk-js: Follows all 10 AXI Principles (Agent eXperience Interface).
Token Frugality (TOON Format): Emits token-efficient, line-based TOON output (~40% cheaper than JSON) so agent context windows stay in the Smart Zone (~150k tokens).
Deterministic Verification: Seamlessly feeds into tasks-axi and no-mistakes verification gates.

🔄 3. The Lifecycle & Workflow

flowchart TD
    Human["👤 Human (Master)"] -->|"Nascent Idea / Broad Prompt"| Frontier["🧭 frontier-axi add <id>"]
    Frontier --> StateToml[".frontier.toml (Staging Lounge)"]
    
    subgraph Cognitive_Sharpening ["Cognitive Sharpening (/grilling)"]
        StateToml <-->|"Interactive Rounds & Q/A"| Grilling["🔥 /grilling & /to-spec"]
        Grilling -->|"Settles Seams & Acceptance Criteria"| Settled["✅ Frontier Settled"]
    end
    
    Settled -->|"frontier-axi promote <id>"| Bridge["🚀 Cognitive Bridge"]
    Bridge -->|"Generates 'What to build' + 'Acceptance Criteria'"| TasksAxi["📋 tasks-axi (Executable Backlog)"]
    TasksAxi -->|"tasks-axi ready"| Maid["🧹 maid Subagents (/tdd)"]
    Maid -->|"no-mistakes gate"| Ship["🚢 Shipped Slice"]

Log the Frontier: Record an ambiguous requirement with frontier-axi add <id> "<title>".
Sharpen without Touching Code: Use /grilling or /grill-with-docs to interview the human, investigate codebase AST/facts, and resolve every open question.
Promote to Executable: Once the frontier is empty, run frontier-axi promote <id>. It synthesizes the verified What to build and Acceptance criteria, calls tasks-axi add, and marks the frontier item closed.
Autonomous Execution: The maid agent picks up the unblocked ticket from tasks-axi ready and implements it test-first.

💻 4. CLI Usage & Ergonomics

frontier-axi is built with axi-sdk-js and conforms to AXI standards:

Content-First Dashboard (AXI Principle #8)

Running with no arguments renders the live frontier state, not help text:

$ frontier-axi
bin: ~/.local/bin/frontier-axi
description: Pre-flight cognitive bridge and frontier tracking CLI
summary:
  active_frontiers: 3
  open_questions: 7
active[3]{id,title,questions,state}:
  auth-seam,Determine session store seam vs JWT,3,grilling
  billing-tiers,Decide metered usage threshold,4,grilling
help[2]:
  - Run `frontier-axi show <id>` to inspect open questions
  - Run `frontier-axi add <id> "<title>"` to stage a new topic

Common Commands

# Stage an ambiguous feature or inquiry
frontier-axi add auth-seam "Determine session store seam vs JWT" --body "We need to choose between Redis or JWT cookies."

# Inspect details and unresolved questions (truncated by default, --full for complete)
frontier-axi show auth-seam --full

# Log an open question during grilling
frontier-axi question add auth-seam "Will we support multi-region session invalidation?"

# Resolve an open question
frontier-axi question resolve auth-seam 1 --answer "Yes, via Redis pub/sub."

# Promote settled frontier to tasks-axi (The Cognitive Bridge!)
frontier-axi promote auth-seam

# Mark done / cancel directly
frontier-axi done auth-seam --reason "Superseded by architecture decision ADR-004"

📦 5. Deterministic Storage (SSOT)

Just as tasks-axi uses backlog.md, frontier-axi maintains a dual-view single source of truth:

.frontier.toml — Machine-readable, structured state for agents.
frontier.md — Clean, human-readable Markdown view with live tables.

🤝 6. Contributing & Ecosystem

frontier-axi is an open-source citizen of the AXI Ecosystem. Contributions targeting main adhere to the no-mistakes verification gate:

git push no-mistakes