Skip to content

SRS.md

Latest commit

 

History

History
148 lines (121 loc) · 7.82 KB

SRS.md

File metadata and controls

148 lines (121 loc) · 7.82 KB
Raw

Software Requirements Specification

1. Purpose

vishwakarma is a local, single-user CLI tool that generates code from a task description, self-heals failing generations, and (opt-in) drives the surrounding SDLC lifecycle — SRS/HLD authoring, Jira sprint planning, and git/GitHub push — through a multi-provider LLM routing layer with automatic failover. This document records vishwakarma's own functional and non-functional requirements; it is distinct from the SRS/HLD files vishwakarma generates for a target project under docs/phase-0-requirements/ and docs/phase-1-architecture/.

2. Scope

In scope: single-developer, local CLI code generation with self-heal; multi-provider LLM failover routing (models.yaml); opt-in chaining of SRS/HLD generation, sprint planning, and git/PR automation into one lifecycle command; adaptive first-candidate routing driven by task complexity. Out of scope is listed in §5.

3. Requirements

3.1 Functional Requirements

FR-001: The system SHALL generate code from a task description and self-heal failing attempts, keeping the best attempt across retries (see ADR-0011).

  • Priority: High
  • Source: pre-existing (engine/orchestrator.py::run_task)
  • Added: 2026-09-14 (documented retroactively as part of this SRS's creation)

FR-002: The system SHALL support an opt-in end-to-end lifecycle command (vishwakarma sdlc full) that chains SRS generation, HLD generation, code generation with self-heal, Jira sprint/epic creation, and git commit/push/PR creation, with each stage individually toggleable and defaulting to off, so that invoking the command with no flags reproduces today's run_task-only behavior exactly.

  • Priority: High
  • Source: this task ("Close the SDLC + Multi-LLM Gaps", Gap A)
  • Added: 2026-09-17

FR-003: When both a Jira sprint/epic and a GitHub PR are created within the same lifecycle run, the system SHALL link the PR back to the originating Jira Epic. A failure to link SHALL be logged and SHALL NOT fail the overall run.

  • Priority: Medium
  • Source: this task ("Close the SDLC + Multi-LLM Gaps", Gap A)
  • Added: 2026-09-17

FR-004: The system SHALL support an opt-in adaptive routing mode (VISHWAKARMA_ADAPTIVE_ROUTING) that selects a role's starting candidate based on the existing task-complexity signal, without reordering or removing any candidate from the role's configured failover chain, and without altering rate-limit handling (ADR-0010) or role-classification rules (ADR-0006). When the mode is off (default), routing behavior SHALL be unchanged from today.

  • Priority: Medium
  • Source: this task ("Close the SDLC + Multi-LLM Gaps", Gap B)
  • Added: 2026-09-17

FR-005: The system SHALL support adding a new LLM provider candidate to a role's configuration gated behind a named environment variable (enable_env), such that the candidate is excluded from the role's failover chain entirely unless that variable is set, enabling dormant providers to be trialed without a code change.

  • Priority: Low
  • Source: this task ("Close the SDLC + Multi-LLM Gaps", Gap B)
  • Added: 2026-09-17

FR-006: The system SHALL support bounded multi-agent tool-call dispatch: during the architecture (Phase A) and implementation (Phase B) model calls, the model MAY invoke a dispatch_agent(task, domain_hint) tool to consult a real specialist agent selected from claude-global-library's knowledge graph, capability-gated per models.yaml candidate (supports_tools) so a candidate without confirmed/claimed tool support behaves exactly as before. Dispatch SHALL be bounded by: (a) nesting depth -- a dispatched specialist's own call never receives the dispatch_agent tool; (b) a per-root-task visited-agent set -- the same specialist is never dispatched twice within one call; (c) a hard token budget ceiling per root task, configurable per provider tier. Every dispatch failure mode (no matching agent, timeout, malformed tool-call arguments, a failed nested call, or an exhausted budget) SHALL degrade to an error-shaped tool result rather than raising an exception that aborts the parent call.

  • Priority: High
  • Source: this task ("close the single-coder-call architecture gap, build real multi-agent dispatch inside vishwakarma")
  • Added: 2026-09-17

FR-007 (follow-up, not built in this pass): The system MAY extend dispatch_agent-style tool dispatch to Phase D (QA) for flaky-test diagnosis, using a distinct diagnostic tool contract rather than the implementation-specialist shape FR-006 defines.

  • Priority: Low
  • Source: this task's ADR, "Rejected: Auto-dispatching QA/flaky-test diagnosis in this same pass"
  • Added: 2026-09-17

3.2 Non-Functional Requirements

NFR-001: Every new opt-in behavior (lifecycle chaining, adaptive routing, gated providers) SHALL default to today's existing behavior when not explicitly enabled, verified by tests that assert no observable difference with the feature off.

  • Priority: High
  • Added: 2026-09-17

NFR-002: No new server, daemon, or multi-tenant surface SHALL be introduced; the tool remains a single-user local CLI (per README's stated scope).

  • Priority: High
  • Added: 2026-09-17

NFR-003: LLM provider/model selection SHALL remain entirely config-driven via models.yaml; no model identifier SHALL be hardcoded in Python source.

  • Priority: High
  • Added: 2026-09-17

4. Acceptance Criteria

AC-FR-002: vishwakarma sdlc full TASK with no flags produces output identical to vishwakarma run TASK (existing command); each of --generate-srs/--generate-hld/ --create-sprint/--push-pr independently toggles exactly its own stage.

AC-FR-003: A test exists asserting link_pr_to_epic returns False and logs an event on MCP failure without raising, and is only invoked when both a sprint and a PR exist in the same run.

AC-FR-004: A test exists asserting that with VISHWAKARMA_ADAPTIVE_ROUTING unset, Router.seed_active_index is never called and primary_coder/reasoner's active index is unchanged from baseline.

AC-FR-005: A test exists asserting a candidate with an unset/false enable_env variable is excluded from load_config()'s resulting candidate list for its role.

AC-FR-006: Tests exist asserting: a candidate without supports_tools: true never receives the dispatch_agent tool schema (plain-chat behavior unchanged); a dispatched specialist's own nested call never carries the tool; the same specialist cannot be dispatched twice within one root call; a nested call exceeding the configured budget returns a budget_exceeded tool result instead of proceeding; and each of NO_MATCH, timeout, malformed-JSON, and nested-call-failure degrades to an error-shaped tool result without raising.

5. Out of Scope

  • Multi-tenant or hosted/server deployment of vishwakarma itself.
  • Automatic (non-opt-in) execution of the full lifecycle chain.
  • Making push_and_create_pr's existing raise-on-failure behavior non-fatal — opt-in via flag is not the same as swallowing failures (see ADR-0013).
  • Live-verifying the openai, anthropic-compatible, or xkiro provider candidates without a real credential present in the environment (see ADR-0014's Deferred/Missing Env outcomes).
  • Any changes to the SRS/HLD files vishwakarma generates for other projects (docs/phase-0-requirements/, docs/phase-1-architecture/) — this document is vishwakarma's own requirements record, not its output template.

6. Change Log

Date Version Task Change Summary Status
2026-09-17 1.1.0 Close the SDLC + Multi-LLM Gaps Created this SRS; added FR-001 (retroactive) through FR-005 and NFR-001..003 for the opt-in lifecycle-chaining and adaptive-routing gaps Done
2026-09-17 1.2.0 Real multi-agent dispatch (close single-coder-call gap) Added FR-006 (bounded multi-agent tool-call dispatch) and FR-007 (follow-up: QA-phase dispatch, not built) with AC-FR-006 Done