- Home
- Skills
- Prompt & Skill Engineering
- specdesk-requirements-to-code
Specdesk Requirements to Code
Local-first spec-driven development for Claude Code, enforcing requirement-to-code traceability and isolated task execution.
$5
Works with the AI Agents you already use
specdesk-requirements-to-code
Example session with this skill installed
I need to implement a User Authentication feature in my existing Spring Boot application.
Can you create a new work item for this feature and generate all the initial specifications required for development?
The feature should support
- User registration with email and password.
- Secure login using JWT authentication.
- Access token and refresh token management.
- Logout and token invalidation.
- Password hashing and secure storage.
- Role-based access control (USER and ADMIN).
- Account lockout after 5 consecutive failed login attempts.
Please analyze the existing repository before proposing the solution.
I want you to
- Create a structured work item.
- Generate functional and non-functional requirements.
- Define the technical design and architecture.
- Document API contracts and request/response examples.
- Create acceptance criteria.
- Break the implementation into actionable development tasks.
- Identify security considerations and edge cases.
- Validate the generated specifications for completeness and consistency.
Do not modify application source code yet. First generate and validate the specifications so that I can review and approve them before implementation.
- Read your context and instructions
- Compiled the specdesk-requirements-to-code
Work Item Created: User Authentication
Work Item ID: AUTH-001
Feature: User Authentication and Authorization
Status: Specifications Generated – Awaiting Review
Priority: High
1. Summary
Created a structured work item for implementing a secure authentication and authorization module in the existing Spring Boot application.
The existing repository was analyzed to establish the implementation context, identify architectural dependencies, and ensure that the proposed solution aligns with the current application structure.
The specifications are organized into independent artifacts for requirements, technical design, API contracts, acceptance criteria, and implementation tasks.
2. Generated Specification Artifacts
The following artifacts have been generated under the new work item's specification directory:
| Artifact | Description | Status |
|---|---|---|
| requirements.md | Functional and non-functional requirements | Created |
| design.md | Architecture, components and security design | Created |
| api-spec.md | REST API contracts and payload examples | Created |
| acceptance.md | Testable acceptance criteria | Created |
| tasks.md | Implementation breakdown and dependencies | Created |
3. Functional Requirements
User Registration
- Allow users to register using email and password.
- Validate email format and enforce password complexity.
- Prevent duplicate account registration.
- Store passwords using BCrypt hashing.
- Return appropriate validation errors.
Authentication
- Authenticate users using email and password.
- Generate signed JWT access tokens.
- Generate refresh tokens with configurable expiration.
- Validate token signature and expiration.
- Support secure logout and refresh token invalidation.
Authorization
- Support USER and ADMIN roles.
- Protect endpoints using role-based authorization.
- Reject unauthorized requests with HTTP 401 or 403.
Account Security
- Lock accounts after five consecutive failed login attempts.
- Implement configurable account lockout duration.
- Prevent brute-force authentication attempts.
- Never expose passwords, tokens or sensitive information in application logs.
4. Technical Design
Proposed Architecture
- Spring Boot REST API
- Spring Security authentication filters
- JWT-based stateless authentication
- BCrypt password encoder
- MySQL persistence layer
- Refresh token management
- Role-based authorization
Authentication Flow
- Client submits login credentials.
- Authentication service validates credentials.
- Password hash is verified.
- JWT access token and refresh token are generated.
- Client uses the access token for subsequent API requests.
- Authentication filter validates the token.
- Authorization rules determine endpoint access.
The implementation must reuse existing repository conventions and security configurations wherever possible.
5. API Contract
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/v1/auth/register | Register a user |
| POST | /api/v1/auth/login | Authenticate user |
| POST | /api/v1/auth/refresh | Refresh access token |
| POST | /api/v1/auth/logout | Invalidate refresh token |
| GET | /api/v1/auth/me | Retrieve authenticated user |
Example login request
{
"email": "user@example.com",
"password": "SecurePassword123!"
}
Example successful response
{
"accessToken": "<jwt-access-token>",
"refreshToken": "<refresh-token>",
"tokenType": "Bearer",
"expiresIn": 900
}
6. Acceptance Criteria
- A new user can register with valid credentials.
- Duplicate email registration is rejected.
- Passwords are never stored in plain text.
- Valid credentials generate authentication tokens.
- Invalid credentials return appropriate errors.
- Five consecutive failed login attempts trigger account lockout.
- Expired access tokens cannot access protected endpoints.
- Refresh tokens can be invalidated during logout.
- USER and ADMIN permissions are enforced correctly.
- Authentication endpoints are covered by automated tests.
7. Implementation Tasks
| Task | Description | Priority |
|---|---|---|
| AUTH-001-T1 | Implement user entity and repository | High |
| AUTH-001-T2 | Implement registration service | High |
| AUTH-001-T3 | Configure Spring Security and JWT | High |
| AUTH-001-T4 | Implement login and token generation | High |
| AUTH-001-T5 | Implement refresh token lifecycle | High |
| AUTH-001-T6 | Implement account lockout | High |
| AUTH-001-T7 | Configure role-based authorization | High |
| AUTH-001-T8 | Implement logout functionality | Medium |
| AUTH-001-T9 | Add unit and integration tests | High |
8. Security and Design Considerations
- Use secure password hashing.
- Keep JWT signing secrets outside source control.
- Implement refresh token rotation.
- Avoid logging credentials and authentication tokens.
- Enforce HTTPS in production.
- Apply rate limiting to authentication endpoints.
- Ensure token invalidation works across application instances.
9. Validation Report
| Validation Check | Result |
|---|---|
| Requirements completeness | Passed |
| Technical design defined | Passed |
| API contracts documented | Passed |
| Acceptance criteria defined | Passed |
| Tasks linked to requirements | Needs final review |
| Security considerations | Passed |
| Implementation readiness | Awaiting approval |
10. Recommended Next Steps
- Review and approve the generated requirements.
- Review the technical design and API contracts.
- Resolve outstanding design decisions.
- Finalize implementation tasks.
- Hand off the approved work item to the AI coding agent for implementation.
Current Status: Specification generation completed. No application source code has been modified.
Next Action: Review and approve AUTH-001 before starting implementation.
Connects securely to your tools. The creator never sees your data.
About this skill
Managing requirements and complex feature implementation manually in Claude Code leads to scope creep and brittle code. SpecDesk forces a spec-driven development cycle that keeps your agent grounded.
What it does
- Spec management Creates and validates requirement, design, and acceptance specs in
.specdesk/items/folders. - Workflow enforcement Prevents code implementation until specs are approved and validation reports show zero errors.
- Isolated execution Implements tasks within dedicated Git worktrees to keep the main branch clean during development.
- Traceability mapping Links every task to specific requirements and acceptance criteria for complete feature coverage.
- Staleness detection Flags downstream artifacts for review when upstream requirements or design files change.
How it works
- Gather Import Jira issues, Confluence pages, or documents and use FSD breakdown to create work items.
- Draft Generate and validate the spec proposal, fixing any structural or logic errors until the report is clean.
- Approve Review the final spec layout and mark the work item as approved to unlock implementation.
- Build Execute tasks one by one, using plan and execute commands to write code within the isolated worktree.
Frameworks & tools
Requires Node.js (v22.22.2+ or v24.15.0+), Git, and the Claude Code CLI. Works locally via a Node.js API and web UI.
Why this beats prompting it yourself
Prompting an agent to "follow a spec" often fails as the context grows and the agent takes shortcuts. This skill provides a hard-coded structure in your repo that the agent cannot ignore, ensuring every line of code satisfies a documented requirement.
Use cases
- Feature breakdown Turning a massive FSD or PRD into individual, trackable work items.
- Safe implementation Running agentic code changes in isolated worktrees with mandatory test passing.
- Audit trails Maintaining a permanent record of design decisions and requirements directly in the repository.
Known limitations
Requires a local Node.js server running on loopback ports 4317 and 5173. Only one implementation run can be open at a time.
Requires local Node.js server (v22.22.2+ or v24.15.0+) on ports 4317/5173. Limited to one active implementation run at a time. Only operates within allowlisted folders.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 9 days ago
Requires
Permissions
Allowed Hosts