Waypoint™ Architecture Decisions, Assumptions and Open Questions

1. Purpose

This document distinguishes settled product/architecture direction from implementation choices that should remain open until planning or architecture spikes.

The implementation team must not mistake an open question for permission to change an approved product requirement.

2. Confirmed design decisions

DEC-001 — Product lifecycle

Waypoint™ uses:

Design → Plan → Execute → Deliver

Allocation/dispatch are responsibilities within Plan/Execute rather than top-level peer lifecycle stages.

DEC-002 — Control Plane

Governance, orchestration, lifecycle state, reporting, worker registry, audit, integrations, and related cross-cutting services belong to a Control Plane.

DEC-003 — Project-type neutrality

Core domain semantics shall not assume software development.

DEC-004 — Canonical Waypoint™ domain

Waypoint™ owns canonical lifecycle semantics. Jira and other providers are projections/integrations.

DEC-005 — Jira operational work ledger

Jira is an important operational work representation when configured, but not the canonical product model.

DEC-006 — Reporting

Reporting and analytics are first-class product capabilities with governed APIs independent of Jira reporting limitations.

DEC-007 — Worker abstraction

Workers include humans, AI agents, agent teams, automations, and external systems.

DEC-008 — Capability-based allocation

Planning expresses capability requirements; runtime execution chooses an authorized worker.

DEC-009 — Durable lifecycle state

LLM conversation or process memory shall not be the system of record for long-running state.

DEC-010 — Evidence-based completion

Work, delivery, and acceptance require appropriate evidence.

DEC-011 — Version-bound approval

Design and Plan approvals bind to exact artifact versions.

DEC-012 — Adaptive execution

Waypoint™ maintains an approved baseline while continuously maintaining the operational plan as execution discovers new information.

DEC-013 — Automatic disposition

Low-risk, in-scope discovered work may be automatically created, scheduled, and executed. Material changes raise gates according to policy.

DEC-014 — Provider adapters

Jira, GitHub, AI runtimes, cloud platforms, delivery systems, and notification systems are integrated through bounded adapters.

DEC-015 — Initial architecture style

Favor a modular architecture with strong domain boundaries over premature microservice decomposition.

DEC-016 — API-first reporting

Native reporting and authorized external reporting should use governed Waypoint™ reporting interfaces.

DEC-017 — Human control

Autonomous work must be observable, interruptible, auditable, and governed.

3. Confirmed software-project policy direction

For Waypoint™'s own development and other projects using the same policy profile:

• branch flow may use feature → preview → main;
• detailed pull requests are required;
• work requires a Task or Bug;
• ticket descriptions must be meaningful;
• execution workers should review ticket comments for owner feedback;
• documentation is maintained with implementation;
• MkDocs Material is preferred;
• strict documentation builds should run in CI;
• PR template compliance should be automated;
• multi-agent work may use Git worktrees;
• temporary worktrees/workspaces should be cleaned/pruned.

These are configurable project/organization policies, not universal core-domain assumptions.

4. Working assumptions

ASM-001 — Jira remains an early integration

The first implementation is expected to use Jira for operational work tracking.

ASM-002 — Git-based software delivery is an early execution path

A development project is expected to be the first deeply automated end-to-end project type.

ASM-003 — AI workers are central

At least one AI-agent runtime will be available for the initial release.

ASM-004 — Human gates remain necessary

Initial production/high-impact delivery will retain human governance even as low-risk execution becomes increasingly autonomous.

ASM-005 — Relational canonical persistence is suitable

A relational database is assumed to be a strong default unless implementation analysis identifies a better fit.

ASM-006 — Reporting projections are necessary

Operational dashboards should not perform expensive cross-provider aggregation on every request.

ASM-007 — Execution history becomes planning intelligence

Actuals/discoveries should be retained in a form suitable for later estimate and planning improvements.

5. Open architecture questions

OQ-001 — Primary application stack

Determine the final application/backend stack.

Selection criteria:

• developer productivity;
• durable orchestration integration;
• API quality;
• background processing;
• observability;
• deployment;
• testability.

OQ-002 — Canonical database

Select the relational database and hosting approach.

Evaluate:

• transactional integrity;
• JSON support where useful;
• event/outbox patterns;
• reporting projections;
• migrations;
• operational cost.

OQ-003 — Workflow/orchestration engine

Determine whether to use:

• database-backed custom durable workflows;
• dedicated workflow engine;
• cloud-native durable orchestration;
• hybrid.

Required capabilities include timers, wait-for-human, retries, cancellation, resume, and long-lived state.

OQ-004 — Event mechanism

Determine initial event implementation:

• transactional outbox + background processor;
• queue/message bus;
• event streaming platform.

Do not introduce infrastructure complexity without a demonstrated need.

OQ-005 — Artifact storage

Select storage for Markdown, generated packages, evidence, and other project artifacts.

OQ-006 — Identity provider

Select authentication/identity architecture and organizational tenancy model.

OQ-007 — Secrets manager

Select secrets/credential storage and short-lived credential strategy.

OQ-008 — First AI-agent runtime

Select the first worker runtime and define its normalized adapter.

The core must remain provider-neutral.

OQ-009 — First delivery provider

Select the first automated delivery path for MVP.

OQ-010 — Jira synchronization mechanism

Determine the balance among:

• webhooks;
• polling;
• explicit reconciliation;
• scheduled drift checks.

OQ-011 — Reporting API style

Determine REST, GraphQL, or mixed approach based on UI and external reporting needs.

OQ-012 — Reporting storage/projections

Determine whether initial projections live in:

• relational tables/views;
• materialized views;
• analytical store;
• hybrid.

OQ-013 — Agent-team orchestration depth

Determine how much subagent/team orchestration belongs in MVP versus immediately post-MVP.

OQ-014 — Cost telemetry

Determine which providers expose reliable cost/usage and the precision needed for MVP.

OQ-015 — Notification providers

Select initial human-notification channels.

OQ-016 — Hosting/deployment

Select the deployment platform for Waypoint™ itself.

OQ-017 — Multi-tenancy

Determine whether initial product is:

• single organization;
• logically multi-tenant;
• fully SaaS multi-tenant.

Schema/security choices should not unnecessarily prevent future tenancy.

6. Open product questions that can be resolved during planning

OQ-018 — Initial autonomy defaults

Set default thresholds for:

• auto-created work;
• estimate variance;
• schedule variance;
• cost;
• risk;
• production impact.

OQ-019 — Sprint behavior for discovered work

Define default rules for inserting discovered work into an active sprint versus a later sprint.

OQ-020 — Baseline amendment thresholds

Define what constitutes a minor operational amendment versus a new approved Execution Plan version.

OQ-021 — First reporting dashboards

Prioritize exact MVP dashboard layouts and metrics from the reporting specification.

OQ-022 — Project template model

Determine whether reusable project templates enter MVP or immediately follow it.

7. Decision process

Open questions should be resolved using one of:

• architecture decision record;
• technical spike;
• prototype;
• benchmark;
• security review;
• owner decision.

Each resolved question should record:

• decision;
• alternatives;
• evidence;
• rationale;
• consequences;
• affected requirements;
• implementation implications.

8. Planning rule

The planning process may create discovery/spike work for unresolved technology choices.

It must not:

• silently invent product requirements;
• weaken governance requirements;
• make Jira canonical;
• make the core dependent on one AI provider;
• remove reporting/API scope;
• eliminate adaptive execution;
• collapse delivery into source-control merge;
• assume all projects are software.

9. Change control

If implementation discovery challenges a confirmed decision:

1. record the issue;
2. identify affected requirements;
3. propose alternatives;
4. evaluate impact;
5. raise the appropriate Design/Architecture gate;
6. approve a revised design decision before implementation proceeds on the changed assumption.