1. Executive Summary
The iBom Mobile project has adopted an AI-driven development workflow that fundamentally transforms how features are built, bugs are resolved, and code quality is maintained. Rather than a single chatbot or assistant, the AI Agent is a tightly integrated ecosystem of three complementary systems: the Specification-Driven Development (SDD) Framework, an Automated Bug-Resolution Pipeline, and GitNexus Code Intelligence.
Together, these systems form a continuous pipeline that converts human-readable requirements into production-ready, fully tested React Native code—with complete traceability from every line of source code back to its originating requirement. This document provides a comprehensive overview of the AI Agent’s architecture, its operational workflow, the tangible benefits it delivers, and practical guidance for team members working within this new paradigm.
2. What Is the AI Agent?
The AI Agent in the iBom Mobile project is not a single bot. It is the combined workflow of SDD automation, a bug-resolution pipeline, and code-graph intelligence wired directly into the repository. Each component serves a distinct purpose while reinforcing the others, creating a development experience that is faster, safer, and more traceable than traditional manual workflows.
2.1 SDD Framework
The Specification-Driven Development Framework is the backbone of the AI Agent’s feature-delivery capability. It generates specifications, architectural plans, task graphs, implementation code, unit tests, and verification reports—all from human-readable requirement documents stored in the project’s documents/ directory. Every artifact it produces is linked to formal requirement identifiers (FR-XXX), ensuring end-to-end traceability.
Core principle: Specs in, shipped code out. The framework enforces a disciplined pipeline in which no code is written without a corresponding specification and no specification is considered complete without a verification pass.
2.2 Bug-Resolution Pipeline
The Bug-Resolution Pipeline automates the journey from a raw ticket on pro.ibom.vn to a merged pull request on GitHub. It crawls the ticketing system, applies OCR to any attached screenshots, categorizes issues by module (MATERIAL, NAV, AUTH, etc.), diagnoses root causes, writes regression tests, applies fixes, and opens pull requests—all without manual intervention.
Core principle: Ticket in, pull request out. Every bug fix begins with a failing test to guarantee that the defect cannot silently recur.
2.3 GitNexus Code Intelligence
GitNexus is the project’s code-intelligence layer, built on a full index of the codebase comprising over 100,000 symbols and 156,000 relationships. It provides semantic search, 360-degree symbol context, impact analysis, and safe multi-file renaming—ensuring that every edit is informed by the code’s actual dependency graph rather than naive text search.
Core principle: Understand the code before you edit it. No function, class, or method should be modified without first running an impact analysis to assess the blast radius.
3. How It Works: The SDD Pipeline
3.1 The Six Stages
The SDD Framework operates through six sequential stages, each producing a well-defined artifact that feeds into the next. This pipeline ensures that every feature progresses from a vague requirement to fully verified, production-ready code through a structured, repeatable process.
| Stage | Command | Description |
| 1. Specify | /specify | Produces formal requirement specifications (FR-XXX) from the documents stored in the documents/ directory. Every requirement receives a unique identifier that persists through all subsequent stages. |
| 2. Plan | /plan | Records the architectural design in DESIGN.md, capturing technology decisions, data-flow diagrams, and component boundaries. |
| 3. Tasks | /tasks | Generates a Directed Acyclic Graph (DAG) of implementation tasks, each with clear acceptance criteria, dependencies, and estimated scope. |
| 4. Implement | /implement | Executes the task DAG using Test-Driven Development: a failing test is written first, then the minimal code to make it pass, followed by refactoring. |
| 5. Verify | /verify | Traces every piece of code back to its originating FR-XXX requirement and runs the full test suite to confirm compliance. |
| 6. Review | /review | Performs a comprehensive quality audit covering coding rules, test coverage, accessibility compliance, and performance standards. |
Each stage is designed to be independently auditable. A team member can inspect the specifications before planning begins, review the task DAG before implementation starts, or verify traceability at any point in the pipeline.
3.2 Autopilot vs. Manual Phases
The SDD Framework offers two modes of operation, allowing the team to choose the level of human oversight appropriate to each situation.
| Aspect | Autopilot Mode | Manual Phases |
| Command | /autopilot mobile | /specify → /plan → /tasks → /implement → /verify → /review |
| Execution | End-to-end automation; all six stages run sequentially without intervention. | Each stage is triggered individually, allowing inspection and manual edits between phases. |
| Artifact Review | Artifacts are produced and verified automatically. | Team members can inspect and modify every artifact (specs, design, tasks) before proceeding. |
| Interruption Recovery | Not applicable. | Use /resume to continue from the last completed stage after any interruption. |
| Best Suited For | Greenfield features, large sweeps, and well-documented requirements. | Complex changes, high-risk modifications, and situations requiring fine-grained control. |
In practice, most teams use Autopilot for standard feature work and switch to Manual Phases when dealing with cross-cutting concerns, sensitive refactors, or changes that touch shared infrastructure.
4. How It Works: Automated Bug Resolution
The bug-resolution pipeline bridges two projects. The first project (ibom-crawling) operates externally: it crawls tickets from pro.ibom.vn, runs OCR on attached screenshots, categorizes each issue by module, and exports a structured categorized_tasks.json file. The second project (ibommobile—this repository) consumes that file and drives each bug through to a pull request.
Stage 1: Crawl and Parse
The crawler pulls tickets from the project management system and applies optical character recognition to any attached screenshots, extracting error messages, stack traces, and UI text that would otherwise require manual reading.
Stage 2: Categorize
Each ticket is automatically categorized by module—MATERIAL, NAV, AUTH, CONSTRUCTION, SELL, TRANSFER, and others—based on its content, tags, and affected components. The output is a machine-readable JSON manifest.
Stage 3: Diagnose
The /bugfix command locates the root cause within the codebase. It leverages GitNexus to trace execution flows related to the reported symptom, examines the call graph of suspect functions, and identifies the specific code path responsible for the defect.
Stage 4: Fix with TDD
A failing test is written first, capturing the exact behavior described in the bug report. The agent then patches the source code until the test passes. This guarantees that the fix is verifiable and that any future regression will be caught immediately.
Stage 5: Open Pull Request
The /automate-git-flow command creates a feature branch, commits the changes with proper traceability annotations (Implements: FR-XXX, Task: #NNNNNN), and opens a pull request on GitHub for human review.
5. How It Works: GitNexus Intelligence
GitNexus provides the AI Agent—and every team member—with deep, graph-aware understanding of the codebase. It indexes over 100,000 symbols and 156,000 relationships, mapping every function call, import, and data-flow dependency into a queryable graph.
| Tool | Purpose | When to Use |
| gitnexus_query | Find code by concept using ranked execution flows, not plain text search. | Exploring unfamiliar code, searching for business logic by intent rather than symbol name. |
| gitnexus_context | 360-degree view of a symbol: all callers, all callees, and every execution flow it participates in. | Understanding a function’s role before modifying it. |
| gitnexus_impact | Blast-radius analysis showing which direct callers (d=1), indirect dependents (d=2), and transitive consumers (d=3) would be affected by a change. | Mandatory check before editing any symbol. HIGH or CRITICAL risk requires team discussion. |
| gitnexus_detect_changes | Pre-commit verification that only the expected symbols and execution flows were affected. | Run before every commit to prevent unintended side effects. |
| gitnexus_rename | Graph-aware multi-file rename that understands the call graph, avoiding the errors of naive find-and-replace. | Any symbol rename across the codebase. |
Impact Risk Levels
GitNexus classifies the impact of any proposed change into three depth levels. Depth 1 (d=1) identifies direct callers and importers that will break if the change is made—these must be updated. Depth 2 (d=2) flags indirect dependents that are likely affected and should be tested. Depth 3 (d=3) highlights transitive consumers that may need testing if they sit on a critical path.
6. Key Highlights
The AI Agent introduces several transformative capabilities to the iBom Mobile development process. The following highlights capture the most significant differentiators.
- End-to-End Automation: From a brief stored in the documents/ folder to fully tested, production-ready code, the Autopilot mode can deliver a complete feature in minutes rather than days.
- 100% Requirement Traceability: Every function, class, and test case is annotated with its originating FR-XXX identifier. The scripts/verify-traceability.py script can validate coverage at any time, ensuring no requirement is left unimplemented.
- Test-Driven Bug Resolution: The bug-resolution pipeline writes a failing test before applying a fix, guaranteeing that every resolved defect has a corresponding regression test that will prevent recurrence.
- Graph-Aware Code Intelligence: GitNexus eliminates guesswork from refactoring by providing precise blast-radius analysis, semantic code search, and safe multi-file renaming based on the actual dependency graph.
- Structured, Auditable Artifacts: Every stage of the SDD pipeline produces a discrete artifact—specifications, design documents, task graphs, tests, and verification reports—that can be reviewed independently by any team member.
- Dual Execution Modes: Autopilot for speed and throughput; Manual Phases for control and precision. The team can choose the appropriate mode for each task without sacrificing the benefits of the pipeline.
- Seamless Integration: The AI Agent operates entirely within the existing repository structure, Git workflow, and CI/CD pipeline. It does not introduce new infrastructure, external services, or deployment dependencies.
7. Benefits
7.1 Accelerated Feature Delivery
The Autopilot mode transforms a project brief into specifications, tasks, code, and tests in a fraction of the time required by manual development. Features that previously took days of planning, implementation, and testing can now be delivered in significantly compressed cycles. The team’s capacity is multiplied without proportional increases in headcount or working hours.
7.2 Complete Requirement Traceability
Every function in the codebase is annotated with its corresponding FR-XXX requirement identifier, and every commit message references the requirements it implements. The scripts/verify-traceability.py utility can validate this coverage across the entire codebase at any time, providing auditable evidence that no requirement has been overlooked or silently dropped.
7.3 Reduced Risk in Refactoring
GitNexus impact analysis eliminates the uncertainty that traditionally accompanies refactoring. Before any edit, the blast radius is quantified: direct callers that will break (d=1), indirect dependents that should be tested (d=2), and transitive consumers that may need attention (d=3). HIGH and CRITICAL risk warnings ensure the team is aware of far-reaching consequences before changes are committed.
7.4 Consistent Quality Standards
The TDD-first approach enforced by both the SDD pipeline and the bug-resolution pipeline ensures that every piece of new code ships with corresponding tests. The /review stage audits coding rules, accessibility compliance (testID and accessibilityLabel on every interactive element), localization correctness, and performance standards—catching issues before they reach production.
7.5 Faster, More Reliable Bug Resolution
The automated pipeline from ticket to pull request removes manual triage overhead and ensures a consistent, repeatable fix process. By writing a failing test before each fix, the pipeline guarantees that resolved bugs cannot silently reappear in future releases.
7.6 Knowledge Preservation
Because the SDD pipeline produces formal specifications, design documents, and task graphs for every feature, institutional knowledge is captured in the repository rather than locked in individual team members’ heads. New team members can onboard faster by reading the structured artifacts that accompany every piece of code.
8. Day-to-Day Guidance
Working effectively with the AI Agent requires adherence to a set of practices that ensure the pipeline’s outputs remain reliable, traceable, and safe. The following guidelines apply to every team member interacting with the codebase.
8.1 Best Practices
- Always run impact analysis first. Before modifying any function, class, or method, run gitnexus_impact to understand the blast radius. If the result returns HIGH or CRITICAL risk, discuss with the team before proceeding.
- Annotate code with requirement identifiers. Every function or class that implements a requirement must include a Requirements: FR-XXX annotation in its docstring. Every commit message must reference the requirements it addresses (Implements: FR-XXX).
- Use the project’s API wrapper exclusively. All HTTP requests must go through Api.get and Api.post from app/constants/Api. Never introduce new HTTP dependencies such as fetch or axios.
- Add testID and accessibilityLabel to every interactive element. This is a strict requirement for automated testing (Detox/WDIO/Appium) and screen-reader support. Components missing these attributes are treated as bugs.
- Let verification complete before committing. Always run /verify to confirm traceability and /review to audit code quality before pushing changes.
- Run gitnexus_detect_changes before every commit. This pre-commit check verifies that only the expected symbols and files were affected by your changes.
- Route all user-facing text through i18n. Never hardcode strings. In functional components, use the useTranslation() hook—never call I18n.t directly.
8.2 Common Pitfalls to Avoid
- Do not use find-and-replace for symbol renaming. Use gitnexus_rename, which understands the call graph and produces accurate, multi-file renames.
- Do not ignore HIGH or CRITICAL risk warnings. These indicate that a change has far-reaching consequences that may break critical paths.
- Do not commit without running gitnexus_detect_changes(). Unverified commits risk introducing unintended side effects.
- Do not call I18n.t directly inside functional components. Always use the useTranslation() hook for proper reactivity and consistency.
- Do not hardcode strings in the UI. Every label, message, and placeholder must go through the i18n layer to support localization.
9. Quick-Reference Command Table
The following table summarizes the most frequently used commands and when to use them.
| Command | When to Use |
| /autopilot mobile | Deliver a complete feature from the documents/ folder in one end-to-end run. |
| /specify → /plan → /tasks | Step through the SDD pipeline manually with inspection between stages. |
| /implement | Execute the generated task DAG with Test-Driven Development. |
| /verify | Validate that every piece of code traces back to a formal requirement. |
| /review | Perform a comprehensive quality audit covering rules, coverage, and accessibility. |
| /bugfix | Diagnose a bug, write a regression test, and apply a fix. |
| bash scripts/pipeline.sh | Run the full crawl-and-fix pipeline end-to-end. |
| npx gitnexus analyze | Re-index the code graph before heavy refactors or after large merges. |
| /resume | Resume an interrupted SDD pipeline from the last completed stage. |
Tip: Before starting any task, always load openspec/specs/TECHNICAL.md and BOUNDARIES.md to ensure you are working with the latest architectural constraints and project rules.
10. Conclusion
The AI Agent in iBom Mobile represents a fundamental shift in how the team approaches software development. By combining specification-driven automation, test-first bug resolution, and graph-aware code intelligence into a single cohesive workflow, the project achieves a level of speed, safety, and traceability that would be impractical to sustain through manual processes alone.
The workflow is straightforward: specifications go in, shipped code comes out—safely. The SDD pipeline (Specify, Plan, Tasks, Implement, Verify, Review) ensures that every feature is built on a foundation of formal requirements and validated through automated testing. The bug-resolution pipeline ensures that defects are resolved systematically, with regression tests that prevent recurrence. GitNexus ensures that every edit is informed by the code’s actual dependency structure, eliminating the guesswork from refactoring.
By following the guidance outlined in this document—running impact analysis before edits, maintaining FR-XXX annotations, using the i18n layer consistently, and letting verification complete before committing—the team can fully leverage these capabilities to deliver high-quality software faster and with greater confidence.
