Evidence-based planning and implementation source of truth for an AI-Assisted Lead Qualification & Smart Routing System.
- Phase 1 — Market & Demand Research: COMPLETE
- Phase 2 — Product Requirements & Business Logic: COMPLETE
- Phase 3 — System Architecture & Technical Design: COMPLETE
- Phase 4 — Technology Selection & Implementation Specification: COMPLETE
- Phase 5 — Implementation Readiness Package: COMPLETE
- Implementation: I-01 through I-13 COMPLETE | I-14 Readiness Assessment: PASSED (150/150)
- Verified benchmark evidence: NOT AVAILABLE YET (requires n8n + PostgreSQL + API keys)
- Portfolio/LinkedIn performance claims: NOT AUTHORIZED UNTIL VERIFIED
| Gate | Description | Status | Tests |
|---|---|---|---|
| I-00 | Repository/bootstrap | ✅ | — |
| I-01 | Database foundation | ✅ | run-i04-tests.sh |
| I-02 | Machine-readable contracts | ✅ | run-i04-tests.sh |
| I-03 | WF-04 validation/normalization | ✅ | run-i04-tests.sh |
| I-04 | WF-03 + durable ingress | ✅ | run-i04-tests.sh |
| I-05 | WF-05 idempotency | ✅ | run-i05-tests.sh |
| I-06 | WF-06 deterministic prequalification | ✅ | run-i06-tests.sh |
| I-07 | WF-07 AI adapter | ✅ | run-i07-tests.sh |
| I-08 | WF-08 decision policy | ✅ | run-i08-tests.sh |
| I-09 | WF-09/WF-13 human review | ✅ | run-i09-tests.sh |
| I-10 | WF-10/WF-11/WF-12 side effects | ✅ | run-i10-tests.sh |
| I-11 | WF-14 global errors | ✅ | run-i11-tests.sh |
| I-12 | WF-15 evaluation harness | ✅ | run-i12-tests.sh |
| I-13 | Security & failure verification | ✅ | run-i13-tests.sh |
| I-14 | Readiness assessment | ✅ | i14-readiness-assessment.js (150/150) |
| I-15 | Portfolio packaging | ⏳ | Requires I-14 benchmark |
Known gaps: 18 documented in docs/readiness/I14_KNOWN_GAPS.md — all are runtime execution gaps requiring n8n + PostgreSQL + API keys. None are specification or planning gaps.
Implementation, coding, testing, and debugging executed with opencode under the repository rules defined in AGENTS.md.
Build a real, testable proof-of-work that can support Mifdlal's effort to win a first freelance client in July 2026 and be adapted for Fiverr, Upwork, Freelancer, Sribulancer, Fastwork, Projects.co.id, LinkedIn, a personal portfolio, and other channels. This is an objective, not a guaranteed outcome.
No fake clients, testimonials, case studies, benchmarks, or unsupported performance metrics. Facts, inferences, assumptions, decisions, implementation results, and verified evidence must remain distinguishable. Final portfolio and LinkedIn claims must come from reproducible implementation/testing evidence.
A fictional B2B AI automation agency receiving inbound project inquiries. This is a demonstration fixture, not a claimed client engagement.
Inbound inquiry → validation → duplicate control → deterministic prequalification → bounded AI semantic analysis → deterministic policy decision → human review when uncertain → controlled routing/system update → notification/follow-up → traceability
AI does not own hard business policy or direct authorization of external side effects.
Before any implementation edit, read AGENTS.md. Then follow the Phase 5 readiness package and the gate order in docs/implementation/opencode-implementation-plan.md.
Prime directive: read before editing; verify before claiming; stop on contradiction; never invent missing requirements or evidence.
- Accepted decision records and the Phase 5 readiness decision.
- Product requirements.
- Business contracts/policy/state machine.
- Architecture.
- Security.
- Implementation specifications.
- Readiness controls.
- Testing artifacts and machine-readable contracts.
- Workflow JSON/code.
Lower-level implementation may not silently redefine higher-level accepted behavior.
- n8n self-hosted
2.30.4, pinned for the implementation/benchmark baseline. - Docker Compose, single n8n instance for MVP/demo.
- PostgreSQL as canonical application/system-of-record database, managed through Supabase for the demo.
- OpenAI Responses API with strict Structured Outputs for bounded semantic analysis; exact model ID is release-pinned after availability/evaluation preflight.
- Telegram Bot API for one internal demo notification adapter.
- Resend API for one consent-controlled transactional email adapter.
- n8n Form Trigger for human-friendly demo intake and Webhook for API/test intake.
- PostgreSQL-backed one-time opaque token mechanism for demo human review.
- No CRM, Redis/queue mode, RAG/vector database, multi-agent framework, or community-node dependency in MVP without a new evidence-based decision.
WF-01 lead-ingress-api
WF-02 lead-ingress-demo-form
WF-03 lead-orchestrator
WF-04 validate-normalize-lead
WF-05 claim-lead-idempotency
WF-06 deterministic-prequalification
WF-07 ai-semantic-analysis
WF-08 qualification-decision
WF-09 human-review
WF-10 route-final-disposition
WF-11 send-telegram-alert
WF-12 send-prospect-email
WF-13 resolve-human-review
WF-14 global-error-handler
WF-15 synthetic-evaluation-runner
I-00 Bootstrap → I-01 Database → I-02 Contracts → I-03 Validation → I-04 Durable Ingress → I-05 Idempotency → I-06 Deterministic Prequalification → I-07 AI Adapter → I-08 Decision Policy → I-09 Human Review → I-10 Side Effects → I-11 Global Errors → I-12 Evaluation Harness → I-13 Security/Failure Verification → I-14 Benchmark Release → I-15 Portfolio Packaging
Do not skip ahead merely because a later workflow is visually easier or more interesting to build.
docs/research/market-research-july-2026.mddocs/research/market-evidence-matrix.mddocs/research/sources.md
docs/product/project-charter.mddocs/product/target-customer.mddocs/product/problem-statement.mddocs/product/positioning.mddocs/product/reference-business-scenario.mddocs/product/product-requirements.mddocs/product/functional-requirements.mddocs/product/non-functional-requirements.mddocs/product/acceptance-criteria.md
docs/business/lead-data-contract.mddocs/business/qualification-policy.mddocs/business/state-machine-and-routing.md
docs/architecture/system-architecture.mddocs/architecture/data-model-and-contracts.mddocs/architecture/reliability-error-handling.mddocs/architecture/observability-and-operations.mddocs/architecture/deployment-and-environments.mddocs/architecture/implementation-methodology.md
docs/security/threat-model-and-controls.md
docs/implementation/technology-selection.mddocs/implementation/workflow-inventory.mddocs/implementation/integration-specification.mddocs/implementation/repository-structure.mddocs/implementation/configuration-and-secrets.mddocs/implementation/opencode-implementation-plan.md
docs/readiness/implementation-readiness-checklist.mddocs/readiness/requirement-traceability-matrix.mddocs/readiness/workflow-definition-of-done.mddocs/readiness/change-control-and-deviation-policy.mddocs/readiness/opencode-session-protocol.mddocs/readiness/phase-5-readiness-decision.md
docs/decisions/phase-1-market-decision.mddocs/decisions/phase-2-product-decision.mddocs/decisions/phase-3-architecture-decision.mddocs/decisions/phase-4-implementation-decision.md
- A requirement without implementation ownership and verification evidence is not complete.
- A workflow that imports successfully is not necessarily done.
- A passing happy path is not a reliability test.
- AI output is not trusted until contract-validated.
- Side effects require deterministic authorization and idempotency protection.
- Human review and automated recommendation remain distinguishable.
- Unexpected failures remain visible and recoverable.
- If implementation evidence disproves a planning assumption, use the documented change-control process rather than silently drifting.
Working name: AI Lead Qualification Agent
Functional positioning: AI-assisted lead qualification, smart routing, controlled follow-up, human review for ambiguous cases, and execution traceability.
The planning and implementation-readiness source of truth is complete. The next authorized work is implementation beginning at I-00 — Repository/Bootstrap, followed strictly by the documented gate order.