AGENTIC · PORTFOLIO TRACKER

Portfolio Tracker: engineering a product end to end with an AI agent

A personal product in seven repositories: I set the requirements, Codex implements them under written rules, and by rule every substantial change starts from a spec and a work item and ends in a version decision; the API, the app and the site then ship through a tagged release.

Drafted with Claude Code from Portfolio Tracker's repositories (state of 3 July 2026) and published in a release Edgardo authorised on 16 November 2026. How this note was written.

In brief

  1. Portfolio Tracker is a read-only personal portfolio tracker, a personal project of mine (my statement of 16 November 2026), built across 7 active repositories, of which only the documentation one is public.
  2. Codex implements it under written rules: by rule, every substantial change starts as a spec and a work item, is validated in stages and records a version or an explicit no-release decision; the API, app and site workflows tag and release each new version, while a public engineering portal built with Docusaurus explains the system.
  3. As of 3 July 2026 the architecture repository held 13 specs, 74 work items in its English task files (57 marked done) and 8 architecture decisions; the API and the app's web version deployed only to development, and nothing here measures users or time saved.
At a glance. Figures carry their date and source; six of the seven repositories are private.
ProductA read-only personal portfolio tracker: it imports statements and trade confirmations, adds daily market data, computes metrics with auditable breakdowns and shows descriptive insights. It gives no advice, places no orders, moves no money and holds no assets.
Repositories7 active ones, coordinated from portfolio-architect; only portfolio-docs is public. A repository for shared contracts is deferred.
StackArchitecture: Markdown, ADRs, and specs with plans and task lists. API: Express, TypeScript, Prisma, PostgreSQL and Zod. App: Expo, React Native, Expo Router and TanStack Query. Site: Next.js, Tailwind CSS and Cloudflare Pages. Database: SQL migrations and PowerShell scripts. Infrastructure: Docker Compose. Docs: Docusaurus.
Method13 specs, 74 work items in the English task files (57 marked Done; the Spanish companions list 2 more, both done), 8 ADRs and 12 lifecycle skills, in the architecture repository; state of 3 July 2026.
VersionsArchitecture 0.1.0, API 0.1.22, app 0.1.28, database 0.1.0, infrastructure 0.1.0, site 0.1.5 and docs 0.1.0. Source: version-manifest.yml, last release on 3 July 2026.
Public linksThe engineering portal, also in Spanish, the product site and the documentation repository. On 16 November 2026 both sites answered 200 (public observation); the site's configuration redirects / to its Spanish version.
AI at runtimeYes, one piece: a language model served locally with Ollama answers a descriptive chat. The API filters the context by user and portfolio and blocks requests for buy or sell advice before calling it.
My statementsPortfolio Tracker is a personal project of mine, not client or employer work; the AI-Driven Development standard the repositories were adopting in phases is my own method; Codex is the agent that implements, and Ollama runs the product's local model. Source: my statement of 16 November 2026.

What Portfolio Tracker is, and what it is not

Portfolio Tracker imports monthly statements and trade confirmations from a broker's PDFs, together with adjusted daily prices from a market data provider. It computes investment, net capital, income, expenses, market value and return, each with a breakdown of the rows behind the figure, and shows them in an app for Android and the web.

Its boundary is written into every repository: the product is read-only. It gives no financial advice or recommendations, executes no trades, routes no orders, moves no money and holds no assets. When a statement or a price is missing, it shows Pending or Partial instead of borrowing a value from another period.

Data rules follow suit: user, portfolio and broker account identifiers are UUIDs, a full account number is never a key nor displayed, and sensitive queries must filter by user and portfolio.

The engineering portal

The most visible piece is the engineering portal, built from the public portfolio-docs repository. It shows how the system fits together without access to the private repositories: 13 pages per language, in English and Spanish, written in Markdown with Docusaurus and illustrated with Mermaid diagrams. It covers:

The portal is built like code. A GitHub Actions workflow builds it on every pull request and publishes it to GitHub Pages from main. The Docusaurus configuration sets onBrokenLinks: 'throw', so a broken internal link fails the build instead of reaching the site. A second workflow, also on main, generates a Markdown copy of the pages and pushes it to the repository's wiki.

What it leaves out is deliberate. By its own scope statement it excludes internal runbooks, secrets, private infrastructure details and users' financial data, its own rules forbid publishing secrets, internal IPs or private URLs, and the spec that governs it allows API and integration concepts without private hostnames. Nothing synchronises it automatically with the other repositories: a public page changes through a work item, like any other change, and so it can fall behind (see what this does not prove).

Architecture in seven repositories

Each repository has one role, its own AGENTS.md with the rules an agent reads first, a changelog and a version:

  • portfolio-architect: the operational memory and the coordination point. Specs, work items, ADRs, skills and the version manifest, in Markdown; no product code.
  • portfolio-api: authentication, imports, calculations, dashboard and chat, with Express, TypeScript, Prisma, PostgreSQL and Zod.
  • portfolio-mobile: the app for Android and the web, with Expo, React Native, Expo Router, TypeScript and TanStack Query.
  • portfolio-web: the commercial site, with Next.js, TypeScript and Tailwind CSS, exported as static pages to Cloudflare Pages. It shows demo screens and makes no calls to the API.
  • portfolio-db: SQL migrations, a development seed and backup and restore scripts in PowerShell.
  • portfolio-infrastructure: local orchestration with Docker Compose: PostgreSQL, the API, SonarQube, Ollama and the observability stack.
  • portfolio-docs: the public portal, with Docusaurus.

At runtime the path is short. The app talks only to the API. The API reads and writes PostgreSQL, takes adjusted daily prices from the market data provider and calls the local model for the chat. The app touches neither the database nor the model, and the model runtime has no access to the database: the API builds the context it receives.

Durable decisions are recorded as ADRs. There are 8, all accepted:

  • 0001, record architecture decisions, and 0002, infrastructure owns local orchestration (30 May 2026).
  • 0003, GitHub backlog traceability; 0004, framework roadmap and exceptions; 0005, release train and versioning; 0006, quality and security gates; and 0007, documentation languages (31 May 2026).
  • 0008, agent orchestration governance (4 June 2026).

The lifecycle: from a requirement to a deployed version

This is the core of the method: the AI-Driven Development standard that the repositories were adopting in phases and that, as I stated on 16 November 2026, is my own. Most steps have a lifecycle skill that the agent loads before acting.

Figure 1. From a requirement to a deployed version, as the architecture repository's rules describe it (state of 3 July 2026).
  1. OWNER · REQUIREMENTI bring a need: a feature, a bug or a change to the method.
  2. SPECCodex classifies it and writes spec.md (with a Spanish companion when in scope): user scenarios, success criteria, scope, product boundary and a compliance assessment.
  3. PLAN AND WORK ITEMSplan.md and tasks.md: each work item gets acceptance criteria in Given/When/Then form, dependencies, a target repository and a GitHub issue, and moves to Ready only when all of that is complete.
  4. SPLIT BY REPOSITORYWork that spans repositories becomes one child task and one pull request per repository; the architecture repository coordinates them but does not mix their code.
  5. STAGED VALIDATIONThe smallest useful check while fixing, the full repository checks once stable, and local SonarQube once before the pull request when available; each repository's GitHub Actions workflow runs again on the pull request.
  6. VERSION DECISIONEach pull request records an unpublished SemVer target or an explicit no-release decision, opens as a draft and requests my review.
  7. COORDINATED RELEASEIn the API, the app and the site, after the merge into main the workflow creates the version tag and the GitHub release; a companion pull request records the new version in version-manifest.yml.
  8. DEPLOYMENTThe new version reaches its environment: the API and the app go to development, the site to Cloudflare Pages and the portal to GitHub Pages.
  9. RETROSPECTIVEWhen I ask for it, a blameless retrospective turns a lesson into a written rule, through a new work item and pull request if the earlier ones are already merged.

Numbering ties it all together. A spec is NNN (for example 011), a work item is NNN-MMM (011-001) and a child task in one repository is NNN-MMM-XX (003-015-01); the branch carries the same number. A work item's status (Ready, In Progress, Active, Review, Done, Blocked or Deferred) lives in the local tasks.md; the GitHub issue only traces the pull request.

The definition of done is written too. Before a pull request is opened, the work must be validated; a user-facing feature must work end to end across infrastructure, API and interface, or the missing layer must be recorded as a Blocked or Deferred child task with its reason; and the work item is marked Done in the pull request's last commit. A parent work item is done only when its child tasks are.

Versions are coordinated through one manifest. Its header, as of 3 July 2026:

system_version: "0.1"
repos:
  architecture: "0.1.0"
  api: "0.1.22"
  mobile: "0.1.28"
  database: "0.1.0"
  infrastructure: "0.1.0"
  web: "0.1.5"
  docs: "0.1.0"
  shared: "planned"
  site: "superseded-by: portfolio-web"
compatibility: "Active repos share MAJOR.MINOR during coordinated releases; PATCH may vary independently."
The version manifest: one line per repository, and a compatibility rule under which active repositories share MAJOR.MINOR during coordinated releases while the patch may vary. portfolio-architect · version-manifest.yml

Quality gates

All 7 repositories run a GitHub Actions workflow on pull requests to main. In the API, after installing dependencies and generating the Prisma client, the checks job runs these steps:

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm test

      - name: Build
        run: npm run build

      - name: Runtime dependency audit
        run: npm run audit -- --omit=dev
The API checks: lint, tests, build and an audit of runtime dependencies. The excerpts in this note are compared on every build with verbatim copies taken from the private repositories, not with the live repositories; the copied files and their commits are listed in /evidence/agentic.json. portfolio-api · .github/workflows/api-ci-cd.yml
  • Release notes come from the changelog. The API release fails if CHANGELOG.md has no section for that version, and the site's pipeline rejects a pull request whose version is already tagged.
  • Dependencies. The API's CI audits runtime dependencies; ADR 0006 delegates alerts to Dependabot (recorded as enabled for the API), and defers license scanning and dynamic security testing.
  • SonarQube, local only. Static analysis runs on SonarQube on the local development machine, and the validation script fails if the quality gate fails. By rule, hosted workflows do not assume access to that machine, so the hosted CI does not run it.
  • Accessibility. The app's web build and the commercial site are scanned with axe and Playwright against WCAG 2.2 AA: critical or serious violations fail the job, and moderate or minor ones are only recorded. The JSON and HTML report is attached to each web release.
  • Strict TypeScript. The API, the app and the site compile with strict enabled.

Delivery and operation

The API shows the whole path. Once the checks pass on main, the workflow creates the SemVer tag (without republishing a version already released), a GitHub release with notes taken from the changelog and the image, tagged with the version, in GitHub's container registry. A last job, on a self-hosted runner, deploys it to the development environment: it applies the database migrations from the new image before recreating the container, stops if they fail, and waits for the container to report healthy.

The app has its own pipeline: on main it releases the Expo web export and its image, triggers an Android preview build and deploys the web version to development. Pushes to the preview branch ship as over-the-air updates on the preview channel, without a new native build. The site deploys its static export to Cloudflare Pages.

Observation stays local as well. An optional profile of portfolio-infrastructure runs an OpenTelemetry Collector that sends traces to Tempo, logs to Loki and metrics to Prometheus, all read from Grafana; by rule it exports nothing to hosted services.

The role of AI

Codex is the agent that implements (my statement of 16 November 2026), and it works under rules written for it. Each repository's AGENTS.md is its entry point; in the architecture repository, two of the workflow rules read:

- Propose a short plan before editing, keep changes small, and follow: 1 task = 1 module = 1 PR.
- Use `codex/NNN-MMM-short-slug` branches, or `codex/NNN-MMM-XX-short-slug` for repo/module child tasks.
A short plan before editing, one task per module and per pull request, and branches named after the work item or the child task. portfolio-architect · AGENTS.md

Coordination follows a written model. ADR 0008, of 4 June 2026, makes the architecture repository the Master Agent and each target repository a Sub-Agent:

The Master Agent owns requirements, specs, Work Item decomposition, dependency ordering, delegation, status aggregation, and architecture memory. Sub-Agents own implementation inside their repo, validation, repo docs, and PR artifacts.

portfolio-architect · adr/0008-adopt-agent-orchestration-governance.md

That is a documented rule, not a record of agents running in parallel: the same AGENTS.md provides that, without sub-agent tooling, the agent documents the delegation plan, executes only the current repository's task and leaves the rest with an explicit status. The 12 lifecycle skills are files in the architecture repository, and one, portfolio-release-version, must be loaded at the start of every agent run.

Unlike the products in my other notes, this one calls a model at runtime: Ollama serves a local language model for a descriptive chat about the user's portfolio. The guarding happens in the API, before the model sees anything: it classifies the question with deterministic rules and, if it asks whether to buy, sell, hold, trade, invest or rebalance, answers with a fixed refusal, records it and does not call the model. Otherwise it builds a capped, sanitised context from the dashboard and data services, filtered by user and portfolio, and sends it to the model through a compatible API.

What I decide

By rule, the agent works inside a scope I set. These decisions stay with me:

  • Requirements and scope. Analysis starts when I bring new work, and the specs write their scenarios from the project owner's point of view; the agent turns it into specs, plans and work items.
  • Review of each pull request. By rule the agent opens the pull request as a draft and requests me as reviewer when GitHub allows it. The files do not record who performs each merge, and branch protection is blocked by GitHub's free plan for private repositories: the review is a rule, not a technical lock.
  • Manual prerequisites. Some steps need me: stable domains, the Android signing fingerprint, secrets in each environment and tests on a physical device. The passkey sign-in spec lists them as manual prerequisites; on 3 July 2026 the development values were in place and the end-to-end validation was still blocked on unmerged changes and a test on a physical device.

What this does not prove

As of 3 July 2026:

  • No store publication recorded. Android ships as internal preview builds.
  • No production environment for the API or the app. The API and the app's web version deploy only to development; the database repository describes staging and production without implementing them. Only the commercial site is public.
  • SonarQube is local only. The hosted CI does not run it.
  • The portal lags behind the architecture repository. Its repository map still lists the public site as deferred, it does not mention portfolio-web or the work of specs 009 to 013, and its workflow page lists 10 of the 12 skills.
  • Gaps visible in the files themselves. The test file named for isolation between users is a placeholder that compares a fixed string, although other route tests check that queries carry user and portfolio filters; the initial migration enables row-level security on 10 tables, but the repository defines no policies; iOS builds are intentionally inactive; and the app's 80% coverage threshold is set in Vitest, but CI runs the tests without coverage.
  • No user or time-saved figures. None are given or claimed.
  • Not financial advice. The product describes records; it recommends nothing.

What comes next

The pending work is already written as work items: finish the passkey sign-in (merge and deploy it, then test it on a physical device), migrate the API module by module to Clean Architecture with a Result pattern, and keep the public portal current under spec 008. If you want to talk about this way of working, get in touch.

How this note was written

This note was drafted with Claude Code from read-only copies of Portfolio Tracker's seven repositories: the latest commits of five of them are from 3 July 2026, and those of portfolio-web and portfolio-docs from 19 June 2026. Facts that are not in the repositories are marked, in the sentence or in the table at the top, as my statements of 16 November 2026 or as public observations made that day. Each statement was traced to its source before publishing. No AI model is named, and no AI tool carries a version, by this site's editorial rule.

Choose optional measurement

Both purposes are off until you choose them. You can change your choice at any time.

Site content, CV downloads, language and theme controls work without optional measurement.