The purpose of this Software Requirements Specification (SRS) is to define the functional and non-functional requirements for Version 1 of Nexus Forge. This document serves as the canonical contract for what the system will do, acting as the foundation for the subsequent Architecture Design phase.
Nexus Forge Version 1 is strictly scoped to bridging the gap between engineering intent and engineering execution. Given a developer's project context and high-level goal, the system will recommend the correct engineering knowledge and generate a reproducible execution plan. It explicitly excludes autonomous code modification, shell execution, or DevOps orchestration.
This document is intended for Software Architects, Systems Engineers, Core Maintainers, and Open-Source Contributors who will design, implement, and verify the Nexus Forge platform.
- Nexus Forge Product Definition (
docs/product/product-definition.md)
Nexus Forge is an Engineering Intelligence Platform that acts as an architectural co-pilot. Instead of writing code, it ingests a developer's engineering intent along with their current project context, queries a repository of structured knowledge, and synthesizes a step-by-step, reproducible execution plan. The system operates purely in an advisory and planning capacity, leaving the actual execution (file modification, command execution) to the developer.
- Responsibilities: Provide project context and clear engineering goals. Execute the resulting plans.
- Goals: Obtain correct architectural guidance and reproducible execution steps without hallucination.
- Expectations: The system must be fast, accurate, transparent, and operate without mandatory paid API usage.
- Responsibilities: Maintain the integrity of the requirements, architecture, and overall vision.
- Goals: Ensure the project remains modular, open-source, and strictly aligned with the MVP scope.
- Expectations: The system design must be highly maintainable and adhere to Clean Architecture.
- Responsibilities: Create and maintain the structured JSON metadata (skills, bundles, workflows).
- Goals: Ensure engineering knowledge is accurately represented and easily queried.
- Expectations: The system must reliably parse and utilize the provided metadata without distortion.
- Developer: The human user interacting with the system to achieve an engineering goal.
- Repository: The physical or virtual codebase being analyzed.
- Repository Context: The structured abstraction of the Repository's current state and constraints.
- Engineering Goal: The specific objective the Developer intends to achieve.
- Knowledge Source: A structured repository of JSON metadata containing engineering patterns.
- Skill: An atomic, structured piece of engineering capability.
- Workflow: A predefined sequence of operations to accomplish a task.
- Bundle: A logical grouping of related Skills and Workflows.
- Recommendation: The system's suggested path forward, derived from the Knowledge Source.
- Execution Plan: The synthesized, step-by-step roadmap for achieving the Engineering Goal.
- Capability: A function that a tool or system can perform.
- Evidence: Supporting information justifying a specific Recommendation.
- Adapter (conceptual only): The boundary responsible for integrating external data or contexts into the system.
Conceptually, "Repository Context" consists of the entirety of the project's engineering state necessary to make informed architectural decisions. It includes:
- Project structure: The directory and file layout.
- Documentation: Existing
README.md, contributing guidelines, and architecture docs. - Dependency manifests: Files like
package.json,requirements.txt,pom.xml, orbuild.gradle. - Configuration files: System and tool configurations (e.g.,
.eslintrc,tsconfig.json,docker-compose.yml). - User-provided engineering goal: The semantic intent provided by the Developer.
- Optional architectural documents: Explicitly provided design decisions (e.g., ADRs).
- Optional design decisions: Past choices that constrain future implementation.
- Constraints: Technical boundaries (e.g., restricted libraries, required language versions, budget limits).
An "Execution Plan" is the primary output artifact of the system. Its conceptual structure must include:
- Objectives: What the plan achieves.
- Prerequisites: What must be true before starting execution.
- Ordered Tasks: The sequential, atomic steps the Developer must manually execute.
- Dependencies: Which tasks block the execution of other tasks.
- Decision Points: Junctions where the user must choose between valid architectural paths.
- Validation Steps: How the Developer verifies a task was completed successfully.
- Risks: Potential failure points or side effects of the plan.
- Expected Outcomes: The final expected state of the repository.
- Completion Criteria: The measurable definition of "done."
- Knowledge References: Traceability links back to the original structured JSON metadata used to formulate the plan.
The conceptual lifecycle of a Developer's interaction with the system flows through the following states:
- Project Loaded: The system identifies the target Repository.
- Context Validated: The system ensures the Repository Context is sound.
- Intent Understood: The Developer's Engineering Goal is captured.
- Knowledge Retrieved: The system queries the Knowledge Source.
- Recommendations Ranked: Discovered knowledge is prioritized against the context.
- Execution Plan Generated: The ranked recommendations are synthesized into a plan.
- Plan Reviewed: The Developer evaluates the plan.
- Plan Accepted: The Developer proceeds to manual execution (terminal state for the system).
- Description: The system must allow the Developer to specify the target Repository.
- Priority: Critical
- Acceptance Criteria: The system successfully registers the Developer's provided URI or filesystem path.
- Description: The system must verify the specified Repository exists and is accessible.
- Priority: Critical
- Acceptance Criteria: The system confirms read access; otherwise, it triggers FR-011.
- Description: The system must extract the Repository Context without mutating the Repository.
- Priority: Critical
- Acceptance Criteria: The system successfully builds a conceptual model containing dependency manifests, configuration files, and project structure.
- Description: The system must capture the Developer's Engineering Goal.
- Priority: Critical
- Acceptance Criteria: The system accepts non-empty, textual input defining the intended outcome.
- Description: The system must validate that the extracted Repository Context is sufficient to proceed.
- Priority: High
- Acceptance Criteria: The system verifies the presence of minimal structural data; otherwise, triggers FR-012.
- Description: The system must query the Knowledge Source using the captured intent and context.
- Priority: Critical
- Acceptance Criteria: The system returns a collection of Skills/Bundles that conceptually align with the input, avoiding unstructured external searches.
- Description: The system must rank the retrieved knowledge based on contextual relevance.
- Priority: High
- Acceptance Criteria: The system produces a sorted list of Recommendations, appending Evidence for the top choices.
- Description: The system must synthesize the highest-ranked Recommendations into an Execution Plan.
- Priority: Critical
- Acceptance Criteria: The system produces a plan that strictly adheres to the Execution Plan Definition (Section 6).
- Description: The system must allow the Developer to request changes to a generated Execution Plan.
- Priority: Medium
- Acceptance Criteria: The system accepts revision input, re-evaluates the context/intent, and outputs a modified Execution Plan.
- Description: The system must present the Execution Plan to the Developer.
- Priority: Critical
- Acceptance Criteria: The plan is rendered in a standard, human-readable format (e.g., Markdown).
- Description: The system must handle inaccessible or non-existent repositories.
- Priority: Critical
- Acceptance Criteria: The system halts execution and returns a discrete "Invalid Repository" error.
- Description: The system must handle scenarios where critical context cannot be extracted.
- Priority: High
- Acceptance Criteria: The system halts and requests the Developer provide missing files or configurations.
- Description: The system must handle invalid JSON metadata within the Knowledge Source.
- Priority: Critical
- Acceptance Criteria: The system logs the malformed file and excludes it from lookup, allowing the system to continue operating.
- Description: The system must identify and handle structurally incompatible recommendations.
- Priority: High
- Acceptance Criteria: The system elevates the conflict to a "Decision Point" in the Execution Plan rather than guessing.
- Description: The system must handle input that cannot be mapped to any known engineering concept.
- Priority: Medium
- Acceptance Criteria: The system asks the Developer to rephrase or clarify the Engineering Goal.
- Description: The system must gracefully handle completely empty repositories.
- Priority: Low
- Acceptance Criteria: The system proceeds with a "greenfield" assumption rather than failing.
- Description: The system must detect when a project utilizes entirely unknown frameworks or languages.
- Priority: Medium
- Acceptance Criteria: The system informs the Developer that specific architectural guidance is unavailable.
- Description: The system must handle when no relevant knowledge matches the intent.
- Priority: High
- Acceptance Criteria: The system informs the Developer it lacks the required knowledge instead of generating hallucinatory plans.
- Requirement: The system must complete Context Extraction (FR-003) and Plan Generation (FR-008) in under 15 seconds for repositories containing fewer than 10,000 files.
- Requirement: The Knowledge Lookup (FR-006) latency must increase by no more than 100ms per 1,000 new skills added to the Knowledge Source.
- Requirement: Core business logic must require zero modifications when integrating new Knowledge Source JSON schemas (handled via Adapters).
- Requirement: The system must successfully generate a valid Execution Plan (or a defined Error State) for 99.9% of inputs without crashing.
- Requirement: When operated locally, the system must have 100% availability, wholly independent of internet connectivity.
- Requirement: The generated Execution Plan must score at an average readability level (e.g., Flesch-Kincaid Grade Level 10-12) to ensure comprehension across all personas.
- Requirement: Any user interfaces built on top of the system must comply with WCAG 2.1 AA standards.
- Requirement: The system must execute deterministically across Windows, macOS, and Linux without platform-specific configurations.
- Requirement: The system must allow developers to explicitly configure the path to the Knowledge Source via a standard configuration file or environment variable.
- Requirement: Every generated Execution Plan must include 100% traceability (Knowledge References) back to the specific JSON metadata utilized.
- Requirement: The system must allow the registration of new data extraction adapters without recompiling the core execution engine.
- Requirement: The system must successfully ingest existing
agentic-awesome-skillsJSON schemas without requiring data migration.
- Requirement: The system must securely parse all metadata, guaranteeing 0% execution of arbitrary shell commands or malicious payloads embedded in JSON.
- Requirement: The system must guarantee that 0 bytes of Repository Context are transmitted externally unless the Developer explicitly enables a remote AI adapter.
- Requirement: All conceptual boundaries and adapters must have 100% coverage in the technical documentation.
- Requirement: The system must fully execute FR-001 through FR-018 while disconnected from the network, assuming local LLM/metadata is configured.
- Requirement: The system must allow swapping of the underlying AI reasoning engine via configuration, requiring zero changes to the business logic.
US-01: Generate Plan from Goal
- As a startup engineer,
- I want to input my goal of "adding authentication" and my current project context,
- So that I receive a reproducible step-by-step plan based on best practices.
- Acceptance Criteria: The system outputs an Execution Plan utilizing standard authentication patterns found in the metadata.
US-02: Traceable Recommendations
- As an engineering lead,
- I want to see which knowledge bundles were used to generate a plan,
- So that I can verify the architecture complies with our standards.
- Acceptance Criteria: The output includes citations (Knowledge References) to the specific JSON metadata used.
US-03: Local Execution
- As a budget-constrained student,
- I want to run the planning engine entirely locally without API keys,
- So that I can learn software architecture for free.
- Acceptance Criteria: The system successfully generates a plan disconnected from the internet.
- Actors: Developer
- Preconditions: The developer has a local project and the system has access to the Knowledge Source.
- Trigger: Developer submits an Engineering Goal.
- Normal Flow:
- System extracts Repository Context.
- System captures User Intent.
- System queries Knowledge Source.
- System ranks Recommendations.
- System generates Execution Plan.
- System presents the plan to the Developer.
- Alternative Flow:
- If multiple valid architectural approaches exist, the system creates Decision Points in the Execution Plan.
- Failure Flow:
- If no relevant knowledge is found, the system triggers FR-018.
- Postconditions: A reproducible Execution Plan is rendered.
- BR-01: Execution plans must always be reproducible.
- BR-02: Recommendations must originate strictly from structured knowledge, not from unguided LLM generation.
- BR-03: MVP features must never perform autonomous repository modifications.
- BR-04: The system must never execute shell commands on the user's machine.
- BR-05: The system must never transmit user code externally without explicit consent.
- BR-06: If knowledge contradicts the user's core principles, it must be ranked lower or discarded.
- C-01: The project must rely exclusively on free and open-source tooling.
- C-02: The project cannot require mandatory paid API keys to function.
- C-03: The product must consume existing
agentic-awesome-skillsJSON metadata and installers without requiring them to be rebuilt. - C-04: The system must prioritize local-first operation whenever practical.
- A-01: Developers want structured plans and are willing to execute them manually.
- A-02: The existing JSON metadata is rich and structured enough to power intelligent search and planning.
- A-03: A local-first architecture is feasible for context processing without prohibitive compute requirements.
- A-04 (Requires Validation): The developer's project context can be adequately captured without requiring deep, real-time AST parsing in Version 1.
- R-01: The provided JSON metadata may lack sufficient detail to generate highly reproducible execution plans.
- R-02: Developers may reject the product if manual execution is deemed too tedious compared to autonomous agents.
- R-03: Accurately ranking architectural knowledge based purely on intent and basic project context is highly complex.
| Requirement ID | Type | Product Goal / MVP Objective | Persona | Core Principle |
|---|---|---|---|---|
| FR-001 - FR-003 | FR | Understand context | All | Local-first |
| FR-004 - FR-005 | FR | Understand intent | All | Simplicity |
| FR-006 - FR-007 | FR | Discover & Recommend knowledge | Student, Lead | Production-quality |
| FR-008 - FR-010 | FR | Generate execution roadmap | All | Production-quality |
| FR-011 - FR-018 | FR | Improve engineering quality (Error handling) | Startup, Lead | Production-quality |
| NFR-001 - NFR-002 | NFR | Planning speed | Solo | Simplicity |
| NFR-003 - NFR-017 | NFR | Modular architecture, security, independence | Lead | Vendor independence, Local-first |
| BR-01 - BR-06 | Rule | Safe, reproducible planning | All | Open-source-first, Local-first |
The following capabilities are explicitly excluded from Version 1:
- Autonomous coding or file modification.
- Automated bug fixing.
- IDE replacement features (syntax highlighting, inline completion).
- Integration with CI/CD pipelines.
- Multi-agent swarms.
- Shell or terminal execution capabilities.
- Infrastructure management and deployment orchestration.
- REQ-Q1: What is the exact schema of the JSON metadata derived from
agentic-awesome-skillsthat the system must ingest? - REQ-Q2: How exactly is "repository context" provided to the system? Is it a manual user input, a file tree snapshot, or an explicit configuration file?
- REQ-Q3: In the event of conflicting metadata (e.g., two bundles recommending fundamentally different architectures for the same goal), what is the definitive resolution rule?