Skip to main content

Project Plan

Documentation Map​

Project Plan

This document is the complete forward project plan for Helpifyr Spindle from the current live baseline through the current governance, RC2, pilot-readiness RC3, and post-RC3 pilot-completion RC4 closure horizon.

It answers four questions in one place:

  1. what already exists
  2. which phase we are currently in
  3. what is still missing per phase
  4. which concrete sprints remain until the project is complete

Executive Status​

Current delivery state​

Helpifyr Spindle is already beyond a bootstrap-only phase.

The current platform baseline is operational and includes:

  • isolated ERPNext v15 stack and host deployment
  • Integration Event, Revenue Event, Supplier Intake, Approval Packet, Sync Cursor, and Product Mapping
  • OpenClaw approval dispatch, callback, settlement execution, sync, and reconcile flows
  • MCP gateway with finance, settlement, staging, and OpenClaw operations
  • production-like tenant setup for Jadda Helpifyr
  • strong regression suite and Gitea CI protection

Current phase​

  • current delivery phase: Post-RC3 Pilot Completion And RC4 Closure
  • current sprint target: GOV4 01
  • phase status: active

Why the project is not “done” yet​

The existing system is strong in:

  • revenue intake
  • supplier intake
  • settlement approvals
  • payment operations
  • OpenClaw integration
  • MCP-based finance operations

The remaining major gaps are now concentrated in post-RC3 pilot-completion work:

  • the generic HiL fallback workflow is still a stub for non-core trigger families
  • recurring subscription billing still stops at draft invoices instead of carrying a controlled submit path
  • the runtime does not yet emit an explicit warning when development-only MCP bypass mode is enabled
  • release metadata and pilot-facing docs still lag the real RC3 status
  • final pilot confidence now requires one more RC-quality pass after those functional completions

Delivery Defaults​

  • sprint length: 2 weeks
  • delivery model: one core team serially, optional parallel teams after Phase 0
  • baseline principle: extend the current live system, do not rebuild it
  • ERPNext remains the system of record
  • OpenClaw remains the agent and approval layer
  • n8n remains the orchestration and HiL workflow layer

Phase Overview​

PhaseNameStatusRemaining SprintsTarget Outcome
BaselineLive core platformDone0Current production-like core
0HiL foundationDone0Configurable autonomous vs. HiL routing
1Finance completionDone0Bank, SEPA, dunning, period close
2ProcurementDone0Vendor to PO to receipt to bill
3Sales and CRMDone0Lead to quote to cash
4ContractsDone0Contract lifecycle and signoff
5HR and payroll orchestrationDone0Employee, leave, expenses, payroll approval
6AssetsDone0Asset lifecycle and visibility
7Compliance and e-invoicingDone0VAT, annual close, structured invoices
8Reporting and intelligenceDone0Dashboards, KPIs, anomaly detection
9Multi-company and consolidationDone0Intercompany and consolidation
10Release hardeningDone0Release candidate and v1.0.0 readiness
StabilizationSimulation, regression, smoke, RCDone0Credible RC with evidence
Finalv1.0 gap closureDone0Close the remaining productization gaps before v1.0.0
GovernancePost-v1 hardening and governanceDone0Close architecture, security, resilience, compliance, and release-governance gaps
Governance ExtensionRC2 blocker closure and operational completionDone0Close the remaining release blocker and harden the proven RC into a stricter RC2
Pilot ReadinessRC3 go-live closureDone0Turn the hardened RC2 into a pilot-ready RC3 with real critical HiL flows and real recurring billing execution
Pilot CompletionRC4 final pilot closureActive4Close the remaining generic HiL, recurring-submit, and runtime-guardrail gaps and produce a final pilot-grade RC4

Baseline — Already Completed​

This work is considered complete enough to act as the foundation for the remaining phases:

  • isolated stack, reverse proxy, host deployment, and health endpoints
  • staged revenue and supplier flows into ERP invoices
  • settlement and payment workflows with approval control
  • OpenClaw delivery, callback, sync, reconcile, and drift visibility
  • MCP tools for operational finance control
  • tenant bootstrap and localization baseline for DE, AT, and CH
  • large automated regression suite with Gitea CI

This means the plan begins from a strong “Phase minus one” baseline, not from zero.

Phase 0 — HiL Foundation​

Goal​

Replace hardcoded approval routing with a configurable matrix and make n8n a first-class HiL target.

What is already done​

  • packet-based approval lifecycle exists
  • OpenClaw approval roundtrip works
  • settlement approval and callback execution work
  • MCP and operational approval tools already exist

What is still missing​

  • configurable approval rules in ERP data
  • generic autonomous vs. HiL evaluation
  • n8n-native HiL execution logging
  • generalized callback path for n8n
  • HiL routing reusable across future domains

Sprints​

  • 0.1 Approval matrix core
    • add Approval Matrix Rule
    • add HiL Execution Log
    • implement services/hil_router.py
    • migrate settlement approval initiation onto matrix evaluation
    • done when one action can resolve data-driven to autonomous or hil_required
  • 0.2 n8n HiL bridge
    • implement services/n8n_hil_bridge.py
    • add n8n_hil_decision callback
    • add n8n workflow templates for payment run, contract, payroll, tax filing
    • done when matrix -> n8n -> callback -> ERP action works end-to-end
  • 0.3 MCP and CI hardening
    • split api/mcp_tools.py into domain modules
    • add HiL MCP tools and contracts
    • extend CI with workflow and contract validation
    • done when modular MCP passes unchanged tool-schema expectations

Phase 1 — Finance Completion​

Goal​

Close the finance domain around bank operations, payment files, collections, and month-end close.

What is already done​

  • invoice creation and submission foundation
  • payment entry creation and settlement approval flows
  • basic receivable and payable views

What is still missing​

  • statement import
  • bank reconciliation engine
  • SEPA export layer
  • dunning engine
  • close checklist and period lock handling

Sprints​

  • 1.1 Bank import and reconciliation
  • 1.2 SEPA payouts and collections
  • 1.3 Dunning and collections policy
  • 1.4 Period close and checklist-based month end

Done criteria for the phase​

  • statements can be imported, matched, and exception-handled
  • payment files can be exported and approval-gated
  • dunning runs operate automatically below thresholds
  • period close blocks incomplete books and exposes blockers through MCP

Phase 2 — Procurement​

Goal​

Extend supplier invoice intake into full procurement and inventory execution.

What is already done​

  • supplier intake staging
  • purchase invoice generation
  • payment follow-up on supplier invoices

What is still missing​

  • vendor onboarding flow
  • RFQ and purchase order logic
  • goods receipt and stock movement handling
  • replenishment and inventory operator tools

Sprints​

  • 2.1 Vendor onboarding and PO approvals
  • 2.2 Goods receipt and inventory effects

Phase 3 — Sales and CRM​

Goal​

Extend revenue ingestion into complete quote-to-cash and subscription operations.

What is already done​

  • revenue event staging
  • sales invoice generation
  • payment and settlement foundation

What is still missing​

  • CRM objects and lead handling
  • quotations and sales orders
  • pricing and discount governance
  • recurring subscription lifecycle

Sprints​

  • 3.1 CRM and quote-to-cash
  • 3.2 Pricing and discount control
  • 3.3 Subscription lifecycle

Phase 4 — Contracts​

Goal​

Add contract lifecycle management as an auditable domain.

What is already done​

  • approval infrastructure that can support contract review later

What is still missing​

  • Contract Registry
  • renewal and notice tracking
  • contract signoff approvals
  • contract-facing MCP tools and reminders

Sprints​

  • 4.1 Contract registry and lifecycle tracking
  • 4.2 Signature and review workflows

Phase 5 — HR and Payroll Orchestration​

Goal​

Cover employee operations while keeping payroll logic delegated to HRMS-compatible foundations.

What is already done​

  • HR groundwork in the ERP model only

What is still missing​

  • employee operations
  • leave and expense approval flows
  • payroll approval orchestration
  • HR-specific MCP tools and policies

Sprints​

  • 5.1 Employee, leave, and expense operations
  • 5.2 Payroll review and approval orchestration

Phase 6 — Assets​

Goal​

Support the asset lifecycle from purchase through depreciation to disposal.

What is already done​

  • assets exist only as baseline ERP capability, not as Helpifyr Spindle delivery scope

What is still missing​

  • acquisition and activation workflows
  • depreciation operators
  • disposal approvals
  • asset registers and MCP visibility

Sprints​

  • 6.1 Asset lifecycle core
  • 6.2 Asset operations visibility

Phase 7 — Compliance, Tax, and E-Invoicing​

Goal​

Make statutory reporting and structured invoicing operationally usable.

What is already done​

  • company localization baseline
  • invoice archive and structured-channel placeholders

What is still missing​

  • VAT return domain
  • tax filing approval workflows
  • XRechnung, ZUGFeRD, and PEPPOL support
  • annual close and audit preparation

Sprints​

  • 7.1 VAT return and filing approval
  • 7.2 Structured invoice support
  • 7.3 Annual close and audit preparation

Phase 8 — Reporting and Agent Intelligence​

Goal​

Expose company health, KPIs, and anomaly signals to agents and operators.

What is already done​

  • finance visibility MCP tools already exist for the current operational subset

What is still missing​

  • management dashboard
  • KPI summary and cashflow forecast
  • anomaly detection
  • board reports
  • reporting MCP resources and prompts

Sprints​

  • 8.1 Dashboard and KPI layer
  • 8.2 Anomaly detection and board reporting

Phase 9 — Multi-Company and Consolidation​

Goal​

Support intercompany operations and consolidated reporting.

What is already done​

  • multi-company baseline setup exists

What is still missing​

  • intercompany invoice and reconciliation logic
  • elimination and translation logic
  • consolidated PnL and balance sheet

Sprints​

  • 9.1 Intercompany operations
  • 9.2 Consolidation and group reporting

Phase 10 — Release Hardening​

Goal​

Turn the domain-complete system into a release-ready product.

What is already done​

  • the repo already has strong local and CI validation for the current scope

What is still missing​

  • cross-domain smoke pack
  • operator handbook and release checklist
  • UAT process
  • performance and security hardening across the full expanded scope

Sprints​

  • 10.1 Cross-domain smoke and release docs
  • 10.2 UAT, security, and release hardening

One core team​

  1. Phase 0
  2. Phase 1
  3. Phase 4
  4. Phase 2
  5. Phase 3
  6. Phase 5
  7. Phase 6
  8. Phase 7
  9. Phase 8
  10. Phase 9
  11. Phase 10

Two teams after Phase 0​

  • Team A: Phase 1 -> Phase 2 -> Phase 6 -> Phase 8
  • Team B: Phase 4 -> Phase 3 -> Phase 5 -> Phase 7 -> Phase 9 -> Phase 10

Definition of Done for Every Sprint​

No sprint is complete unless all of the following are true:

  • Gitea CI is green
  • relevant MCP docs and contracts are updated
  • tests cover happy path and guarded path
  • at least one smoke path exists for the delivered domain
  • no regression in MCP catalog or existing core coverage

Quality Gates​

  • New business modules target at least 85% coverage
  • Reporting and consolidation target at least 80%
  • Existing high-coverage core modules may not regress below their current level
  • Phase 0 to 3 work must include OpenClaw or n8n loop coverage
  • Phase 1, 7, and 9 require Docker-near integration verification

Remaining Sprint Count and Practical Timeline​

  • remaining issue-sized slices in the documented queue: 4
  • expected duration with one team: ~8 weeks
  • expected duration with opportunistic parallelism: ~5 to 6 weeks

The historical delivery roadmap, stabilization phase, final v1.0 gap closure, first governance queue, governance-extension RC2 queue, and pilot-readiness RC3 queue are complete. The active planning horizon is now the explicitly documented post-RC3 pilot-completion RC4 queue.

Governance Extension And RC2 Closure​

The first governance queue materially closed the original architecture gaps, but the RC deep-dive still identified one remaining release blocker and several high-value closure items that should be handled before treating the stack as governance-complete.

Critical RC2 blockers​

  • unauthenticated MCP fallback path must be removed or explicitly restricted to dev-only mode
  • DB-level uniqueness must protect the highest-risk orchestration doctypes

High-priority closure items​

  • rate limiting for authenticated MCP usage
  • dead-letter uniqueness and remaining idempotency headers for external HiL dispatch
  • completion of missing scheduled automation jobs
  • completion of missing HiL n8n workflow templates
  • deeper security, auth, callback, and connector regression coverage

Governance extension queue​

  1. GOV2 01 MCP auth enforcement and rate limiting
  2. GOV2 02 DB uniqueness and remaining concurrency closure
  3. GOV2 03 scheduler completion and automation coverage
  4. GOV2 04 template completion and security regression depth
  5. GOV2 05 full-stack revalidation and RC2 creation

Governance extension acceptance​

The governance extension is only complete when:

  • MCP tool execution cannot bypass auth by omitting the API key
  • authenticated MCP traffic is rate-limited with explainable operator visibility
  • critical orchestration doctypes are protected by DB-level uniqueness
  • remaining high-risk concurrency gaps are closed or explicitly proven safe
  • missing scheduler jobs are implemented and covered
  • missing HiL templates are checked in and validated
  • the enlarged security and simulation regression suite is green
  • two new live-adjacent verification runs produce a green RC2 for the current runtime revision

Pilot Readiness And RC3 Closure​

The RC2 queue closed the technical blocker set from the governance review, but the latest RC2 deep-dive still leaves a short list of product-completion items that matter directly for real pilot usage.

Pilot-readiness gaps​

  • the critical HiL n8n workflows for contract signing, payment run, payroll, and tax filing are still importable stubs rather than complete approval UIs with callback wiring
  • generate_subscription_invoices still runs in review-only mode instead of creating real recurring invoices
  • a few production-safety and consistency items should be made explicit before go-live:
    • production warning for MCP_ALLOW_UNAUTHENTICATED
    • explicit transaction durability in integration_events
    • safer final fallback shape for n8n HiL idempotency keys

Pilot-readiness queue​

  1. GOV3 01 Production guardrails, transaction durability, and idempotency closure
  2. GOV3 02 Critical HiL workflow completion
  3. GOV3 03 Recurring subscription posting and operator automation completion
  4. GOV3 04 Full-stack revalidation and RC3 creation

Pilot-readiness acceptance​

The pilot-readiness queue is only complete when:

  • production docs and examples make the unauthenticated MCP bypass explicitly forbidden outside development
  • integration_events.record_event persists with explicit transaction intent where required by the service model
  • the final fallback n8n HiL idempotency key no longer collapses repeated same-company requests into one opaque key
  • the critical contract, payment, payroll, and tax HiL workflows are real callback-capable n8n workflows rather than webhook-only stubs
  • recurring subscription automation can create controlled, explainable invoices instead of only review notifications
  • the enlarged regression, simulation, live-smoke, and RC evidence is green for the new runtime revision

Post-RC3 Pilot Completion And RC4 Closure​

The RC3 queue closed the critical pilot blockers, but the latest review still leaves a short set of pilot-grade completion items that should be handled as one explicit final queue instead of ad-hoc follow-up fixes.

Pilot-completion gaps​

  • the generic HiL fallback workflow still behaves as a minimal importable stub instead of a signed callback-capable approval path for the remaining trigger families
  • recurring subscription automation still stops at draft invoices and lacks a controlled submit path for pilot operation
  • the runtime does not emit a visible startup warning when MCP_ALLOW_UNAUTHENTICATED=true
  • release metadata and README state still lag the actual RC3/pilot-ready posture

Pilot-completion queue​

  1. GOV4 01 Runtime guardrails and release metadata alignment
  2. GOV4 02 Generic HiL fallback workflow completion
  3. GOV4 03 Recurring subscription invoice submit-path and automation completion
  4. GOV4 04 Full-stack revalidation and RC4 creation

Pilot-completion acceptance​

The pilot-completion queue is only complete when:

  • the runtime emits an explicit warning whenever development-only unauthenticated MCP mode is enabled
  • release metadata and pilot-facing docs reflect the actual RC3/RC4 state
  • the generic HiL fallback workflow is callback-capable, signed, and import-verified on the host
  • recurring subscription automation can move from eligible subscription state to controlled submitted invoice state with idempotent operator visibility
  • the enlarged regression, simulation, live-smoke, and RC evidence is green for the new runtime revision

Post-Roadmap Stabilization Phase​

When the documented implementation backlog is exhausted, the project is not automatically production-ready. It then enters an explicit stabilization phase focused on realistic verification, simulation of missing external systems, live-adjacent smoke testing, and bug fixing.

Stabilization 01 — External System Simulation Harness​

Goal

  • build realistic test harnesses for the external or not-always-available systems that the delivered domains depend on

Focus areas

  • bank connector and statement-provider simulation
  • contract/support workflow simulation where real integrations are not always available
  • tax/export and document-channel simulation
  • MCP-facing fixtures for domain interactions that are currently only partially covered

Acceptance

  • the most important external-facing domains can be exercised without hand-waving
  • missing dependencies are simulated in a repeatable way

Stabilization 02 — End-to-End Domain Regression​

Goal

  • run the delivered finance and ops modules as real domain flows rather than isolated unit fragments

Focus areas

  • approval to execution paths
  • import to reconciliation paths
  • payout, dunning, close, procurement, sales, contract, HR, tax, reporting, intercompany flows
  • MCP and operator-facing paths that sit on top of those domains

Acceptance

  • documented end-to-end regression evidence exists for the important domains
  • gaps become explicit bug-fix slices instead of hidden assumptions

Stabilization 03 — Live And Docker-Near Smoke Pack​

Goal

  • verify the domains that require environment confidence against the closest safe runtime environment available

Focus areas

  • Docker-near or live-adjacent smokes for the domains explicitly called out in the quality gates
  • non-destructive smoke packs for bank, tax, intercompany, and workflow-orchestration surfaces where appropriate
  • release-smoke coverage across the expanded domain set

Acceptance

  • smoke evidence exists for the environment-sensitive domains
  • environment-specific failures are reproduced and either fixed or clearly documented

Stabilization 04 — Bug Bash And Release Candidate​

Goal

  • turn the findings from the regression and smoke passes into a credible release-candidate state

Focus areas

  • bug fixes from the stabilization findings
  • hardening of error handling, docs, UAT, and release readiness
  • final release-candidate evidence and explicit residual-risk list

Acceptance

  • the product reaches a release-candidate state backed by evidence, not only by implemented modules

Final v1.0 Gap-Closure Phase​

The current codebase is functionally broad and has already reached a credible release-candidate state, but the remaining path to a tighter v1.0.0 requires a final explicit gap-closure phase.

Critical gaps to close before v1.0.0​

  • split apps/jhf_spindle_core/jhf_spindle_core/api/mcp_tools.py into maintainable domain modules
  • replace structured-invoice aliases with real XRechnung/ZUGFeRD output generation
  • implement a real annual close service instead of phase-level placeholders only
  • complete SEPA direct debit support (pain.008) alongside credit transfer
  • complete subscription lifecycle support
  • close the order-to-cash gap with delivery note / Delivery Note support

Important gaps that should be closed before v1.0.0​

  • goods receipt and 3-way match
  • RFQ flow
  • inventory/lager service
  • scheduled jobs such as depreciation and contract renewal
  • expense reimbursement flow
  • richer MCP prompts and resources
  • update docs/PROJECT_PLAN.md so it reflects implemented reality rather than the old phase-zero baseline narrative

Nice-to-have items that can remain after v1.0.0 if needed​

  • MT940 parser in addition to CAMT.053
  • ELSTER XML export
  • FinanzOnline export
  • separate consolidated balance sheet and P&L tools

Final v1.0 queue​

  • Final 01: architecture and plan alignment
  • Final 02: statutory outputs and finance close completion
  • Final 03: order-to-cash and subscription completion
  • Final 04: procurement, inventory, scheduling, expenses, and MCP completion

Final acceptance for v1.0.0​

The product is only truly ready for v1.0.0 when all of the following are true:

  • roadmap queue is complete
  • stabilization queue is complete
  • second pass is complete
  • final v1.0 gap-closure queue is complete
  • final smoke, live-adjacent, and RC evidence reflects the post-gap-closure state

Post-v1 Hardening And Governance Phase​

The current codebase is functionally broad and already passed the final v1.0 gap-closure queue, but the platform still has structural blind spots that must be closed before it can be treated as a robust autonomous enterprise backbone.

Critical governance gaps​

  • no event bridge for manual or foreign-origin ERP activity
  • open or under-authenticated MCP and callback surfaces
  • limited retry, stale-work, and dead-letter handling
  • race windows on approvals, payments, closes, and cursor updates
  • no operational outbound document dispatch
  • missing GoBD and DSGVO workflows beyond the current finance-close baseline

Governance queue​

  • GOV 01: event bridge and manual-origin visibility
  • GOV 02: MCP security and callback authentication
  • GOV 03: resilience, retry, and dead-letter recovery
  • GOV 04: concurrency and idempotency hardening
  • GOV 05: document dispatch and outbound channels
  • GOV 06: GoBD, DSGVO, and finance-close compliance
  • GOV 07: full-stack regression refresh and RC recreation

Governance acceptance​

The governance phase is only complete when:

  • manual and foreign-origin documents are visible through Helpifyr Spindle eventing
  • MCP and callback ingress are authenticated and auditable
  • failed external operations can retry or land in a visible dead-letter queue
  • critical finance and approval paths are protected against duplicate execution
  • outbound dispatch exists for key documents
  • compliance operators exist for retention, DSAR, and subject export
  • the refreshed RC is green twice on the live-adjacent host

Governance Extension And RC2 Phase​

The first governance queue has already been implemented and verified, but the RC deep-dive still found a small number of important closure items that are better handled as an explicit final queue instead of informal follow-up.

RC2 closure gaps​

  • MCP still tolerates an unauthenticated execution fallback path
  • rate limiting is still missing from the authenticated gateway
  • several orchestration doctypes still rely on application logic instead of DB-level uniqueness
  • a few scheduler jobs remain incomplete
  • some HiL workflow templates are still missing
  • security and thinner integration modules need deeper targeted regression coverage

RC2 queue​

  • GOV2 01: MCP auth enforcement and rate limiting
  • GOV2 02: DB uniqueness and remaining concurrency closure
  • GOV2 03: scheduler completion and automation coverage
  • GOV2 04: template completion and security regression depth
  • GOV2 05: full-stack revalidation and RC2 creation

RC2 acceptance​

The RC2 queue is only complete when:

  • the MCP gateway requires auth for productive tool execution
  • rate limiting is enforced and operator-visible
  • the critical orchestration doctypes are uniqueness-protected at DB level
  • missing scheduler jobs and HiL templates are completed
  • the enlarged regression suite is green
  • two fresh live-adjacent verification runs produce a green RC2 on the current runtime revision

Final acceptance for the whole project​

The product is only truly ready for completion when all of the following are true:

  • roadmap queue is complete
  • stabilization queue is complete
  • second pass is complete
  • final v1.0 gap-closure queue is complete
  • post-v1 hardening and governance queue is complete
  • governance-extension RC2 queue is complete
  • pilot-readiness RC3 queue is complete
  • post-RC3 pilot-completion RC4 queue is complete
  • final smoke, live-adjacent, and RC evidence reflects the governance-hardened state

License notice: AGPLv3 (GNU Affero General Public License v3.0)
Website: https://helpifyr.com