TeksPlan: writing a good request, answering questions, approvals

TeksPlan is the first stage of the Tekspaz lifecycle. Instead of writing code on an unvalidated guess, TeksPlan turns your problem statement into a thoroughly reviewed, typed Plan Bundle ready for autonomous coding agents.

A panel of 7 specialized AI agents debates your requirement, challenges ambiguities, designs the architecture and schema, breaks down implementation tasks, and assesses project risks before a single line of code is committed.

---

1. How TeksPlan works

When you submit a project request, TeksPlan initiates a multi-agent debate loop:

1. Interrogation: Agents examine the prompt, compare it against known patterns, and surface missing business requirements or technical trade-offs.
2. Clarification: If requirements are ambiguous, TeksPlan halts and presents targeted multiple-choice questions to you.
3. Synthesis: The 7 specialists author their respective sections of the Plan Bundle.
4. Human Gate: You review the generated plan, inspect the architecture, and either Approve it to proceed to TeksBuild or Request changes.

flowchart LR
    A["Intent / Problem Statement"] --> B["7-Agent Specialist Panel"]
    B --> C{"Ambiguities?"}
    C -- "Yes" --> D["Clarification Questions"]
    D --> B
    C -- "No" --> E["Plan Bundle (v1)"]
    E --> F{"Human Approval Gate"}
    F -- "Approve" --> G["TeksBuild Execution"]
    F -- "Request Changes" --> H["Plan Iteration (v2)"]
    H --> B

---

2. Writing a good request

The quality of the generated architecture directly reflects the clarity of the problem statement. Follow these guidelines for high-signal requests:

The High-Signal Request Formula

A great request answers three questions:

1. The Core Job: Who is the user, and what job are they trying to do?
2. Key Constraints: Are there existing databases, external APIs, authentication requirements, or rate limits?
3. Acceptance Criteria: How will you know the software works?

Concrete Examples

❌ Weak Request (Ambiguous)

“Make an app for customer invoices.”

Why it struggles: No details on who accesses it, whether payment processing is required, where invoices come from, or what data storage is expected.

✅ Strong Request (High Signal)

“Build a customer invoice portal for B2B accounts. Accounts sign in with magic links. Customers can view their unpaid invoices, download invoices as PDF, and pay via Stripe Checkout. Webhooks from Stripe should update invoice status in PostgreSQL to ‘paid’ and send a receipt email via Resend. Include an admin screen for our finance team to issue manual credit adjustments.”

Why it succeeds: Specifies user personas, authentication method, payment provider, webhook events, database choice, and secondary administrative requirements.

Tips for writing intents

• State what you don’t want: If you want zero external dependencies or no third-party cookies, state it upfront (e.g. “Use SQLite for zero-config persistence”).
• Mention integrations: Name your third-party systems early (e.g. “Connect to Snowflake warehouse for read-only aggregation”).
• Keep it conversational: You don’t need formal Jira tickets; write as if briefing a senior staff engineer.

---

3. Answering the planner’s questions

When your request has multiple viable paths (e.g., SQLite vs PostgreSQL, session cookies vs JWTs, polling vs webhooks), TeksPlan pauses and presents a Clarification Questionnaire:

• Recommended Option: The panel highlights a recommended answer based on your project archetype and best practices.
• Click to Choose: Select the answer that fits your organizational standards.
• Custom Answers: If none of the options fit, type your own custom instruction in the response box.

Once all questions are answered, the panel resumes and incorporates your decisions directly into the data models and API contracts.

---

4. Inspecting the Plan Bundle

Every generated plan produces a structured Plan Bundle divided into distinct engineering artifacts:

Section	Content	Key Owners
Requirements	Functional and non-functional requirements, edge cases, user personas.	Product Manager, Business Analyst
Workflows	User journeys, state machines, and lifecycle transitions.	Business Analyst
Architecture	System components, data flow diagrams, external dependencies.	Solution Architect, Researcher
Data Model	Typed Drizzle ORM / SQL schema definitions, relations, and indexes.	Solution Architect
APIs	OpenAPI 3.1 specification for all REST endpoints and payloads.	UI / API Designer
UI Components	Screen layouts, component hierarchies, and interactive states.	UI Designer
Tasks & Estimates	Sequenced atomic development tasks with complexity ratings.	Estimator
Risk Analysis	Security threats, scalability bottlenecks, and mitigation strategies.	Risk Reviewer

You can inspect each tab in the project dashboard (/projects/[id]/plan) before taking any action.

---

5. Approving or requesting changes

TeksPlan enforces a strict Human Authorization Gate:

Approving the plan

1. Review the generated Plan Bundle in your project overview.
2. Verify that the OpenAPI contract and Data Model match your expectations.
3. Click Approve Plan (v1).
4. The plan status updates to approved, locking the architecture version and triggering TeksBuild to begin task decomposition and code generation.

Requesting changes

If you want to alter an architectural decision or add a missed requirement:

1. Click Request Changes.
2. Enter your feedback in the revision prompt:

   Switch the database from SQLite to PostgreSQL with pgvector, 
   and add an API endpoint for vector similarity search over ticket titles.

3. Click Submit Revisions.
4. The 7-agent panel re-convenes, updates only the affected bundle components, and issues Plan v2 with a clear diff highlighting what changed.

---

What to explore next

• TeksBuild: execution loops, sandboxes, and code review
• Connect GitHub and Vercel
• API and CLI for developers