Organization of Project Specification Documents#

CipherSwarm organizes its project specification documents using a phase-prefixed naming convention. Each major development milestone or architectural concern is assigned a sequential phase, and all related specification files are grouped under a directory named for that phase. For example, core infrastructure documents are located in .kiro/specs/phase-1-core-infrastructure/, API implementation in .kiro/specs/phase-2-api-implementation/, and agent management integration in .kiro/specs/phase-3b-agent-management-integration/ source.

Within each phase directory, documents are further divided by purpose, typically including requirements.md, design.md, and tasks.md. This structure enables clear traceability of requirements, design decisions, and implementation plans for each architectural phase.

Core Infrastructure Phases and Specification Content#

Database#

The database specification defines foundational requirements for model structure, connection management, and multi-tenancy. It mandates the use of ActiveRecord with PostgreSQL, connection pooling, health check endpoints, and consistent model patterns. Models must include standard fields (id, created_at, updated_at), enforce unique indexes, and maintain proper foreign key relationships. Enum validations are required at both the application and database level source.

Authentication#

Authentication requirements specify comprehensive user management using Devise, with support for roles (admin, analyst, operator), sign-in tracking, account locking, and password reset flows. The system enforces unique constraints on user identifiers and integrates role-based access control using CanCanCan and Rolify. For agents, authentication is handled via bearer tokens, with secure token generation and validation source.

Agent Management#

Agent management specifications cover agent registration, authentication, state tracking (active, error, offline, pending, stopped), and device metadata. Agents are associated with users and projects, support advanced configuration via JSON fields, and maintain device lists. The system uses a state machine for agent lifecycle management and enforces uniqueness on agent tokens and labels. Administrative workflows include agent registration, project assignment, hardware configuration, and performance monitoring source.

Error Tracking#

Error tracking requirements define the AgentError model, which stores error messages, severity levels, error codes, and metadata as JSON. Errors are linked to agents and optionally to tasks, with indexed fields for efficient querying. The system provides comprehensive error reporting, structured error responses, and real-time notifications for critical events source.

Attack Configuration#

Attack configuration specifications support complex password cracking strategies, including attack modes (dictionary, mask, hybrid), mask parameters, performance tuning, Markov chain settings, rules, custom charsets, and scheduling. The Attack model uses enums for attack modes, supports state transitions via a state machine, and maintains associations with campaigns and resource lists. The system provides validation, keyspace estimation, and template support for all hashcat modes source.

Example: Phase-Prefixed Specification Structure#

.kiro/specs/
  phase-1-core-infrastructure/
    requirements.md
    design.md
    tasks.md
  phase-2-api-implementation/
    requirements.md
    design.md
    tasks.md
  phase-3b-agent-management-integration/
    requirements.md
    design.md
    tasks.md
  phase-6-monitoring-testing-documentation/
    requirements.md
    design.md
    tasks.md

Each requirements.md details user stories and acceptance criteria for the phase. design.md provides architectural diagrams, model definitions, and rationale. tasks.md breaks down implementation steps, validation, and testing plans.

Relationship to Overall Architecture#

The phase-prefixed specification documents directly map to the system's layered architecture and development lifecycle. Each phase builds on the previous, starting with core infrastructure (database, authentication, agent/task/attack models), then expanding to API surfaces, agent workflows, and monitoring. The documents define the requirements and design for each architectural layer, ensuring that implementation, validation, and integration are traceable and cumulative.

For example, the Phase 1 documents establish the foundational models and relationships, which are then extended in Phase 2 with API endpoints and service layers, and further integrated in Phase 3 with agent management workflows and cross-component integration. Later phases address monitoring, testing, and documentation, ensuring system reliability and maintainability source.

Architectural Diagram#

This structure ensures that each specification phase is self-contained, traceable, and aligned with the evolving architecture of the CipherSwarm system.