SDLC Execution Platform

1. Installation

The dedicated installation guide walks you through every step — OS check, Java, API key, first run, and all failure cases.

The quick summary if you already have Java 17+:

What you need before you start:

• A Windows, macOS, or Linux computer (64-bit)
• Java 17 or later — check with java -version
• An Anthropic or OpenAI API key
• A software project on your machine to run the pipeline against

Step 1 — Check your operating system

Windows: Press Win + R, type winver, press Enter. You need Windows 10 (build 1903 or later) or Windows 11. Windows 7 and 8 are not supported.

macOS: Click the Apple menu → About This Mac. You need macOS 12 Monterey or later. Go to System Settings → General → Software Update to upgrade if needed.

Linux: Any modern 64-bit distribution works (Ubuntu 20.04+, Debian 11+, RHEL 8+, Fedora 36+). Run uname -m — you need x86_64 or aarch64. 32-bit systems are not supported.

Step 2 — Check if Java is installed

Open a terminal (macOS/Linux) or Command Prompt / PowerShell (Windows) and run:

java -version

Happy path: You should see something like:

openjdk version "21.0.3" 2024-04-16
OpenJDK Runtime Environment ...

The first number after version " is the major version. If it is 17 or higher, skip to Step 3.

Failure cases:

Install Java (skip if Step 2 passed)

The recommended distribution is Eclipse Temurin — free, open-source, and widely used in production.

Windows:

1. Go to adoptium.net/temurin/releases/?version=21
2. Select: Version 21, Operating System Windows, Architecture x64, Package Type JDK
3. Download the .msi installer and run it
4. When asked, check both "Set JAVA_HOME variable" and "Add to PATH"
5. Close and reopen your terminal, then run java -version

If you still see 'java' is not recognized after reopening: search "Environment Variables" in the Start menu, open "Edit the system environment variables", and verify a path ending in \Java\jdk-21\bin appears in the Path variable.

macOS with Homebrew:

brew install --cask temurin@21

macOS without Homebrew: Download the .pkg from adoptium.net. Select macOS and your architecture — x64 for Intel, aarch64 for Apple Silicon (M1/M2/M3).

Ubuntu / Debian:

sudo apt-get update && sudo apt-get install -y default-jdk-headless

If that installs an older version, use the Adoptium apt repository as described at adoptium.net/installation/linux.

RHEL / Fedora:

sudo dnf install java-21-openjdk-headless

After installing, close your terminal, open a new one, and run java -version again. Do not proceed until you see version 17 or higher.

Step 3 — Get an API key

The platform calls an LLM to generate execution plans and code. You need one of:

Anthropic (recommended): Sign up or log in at console.anthropic.com, go to API Keys, and create a key. It starts with sk-ant-. Save it — you cannot view it again after closing the page.

OpenAI (alternative): Go to platform.openai.com/api-keys and create a new secret key. It starts with sk-.

You only need one key. Keep it private — do not share it or commit it to source control.

Step 4 — Download the JAR

Download sdlc-orchestrator.jar from bakalarsoftware.com/dl/sdlc-orchestrator.jar. Save it somewhere you can find it.

Failure cases:

Step 5 — Verify the JAR runs

Open a terminal, navigate to the folder where you saved the JAR, and run:

java -jar sdlc-orchestrator.jar --help

Happy path — what you should see:

SDLC Execution Platform vX.Y.Z
Usage: sdlc [flags]
  --ticket-id ID        Ticket identifier to process
  --project /path       Path to the target project root
  ...

Failure cases:

Step 6 — Create the config file

The platform reads its configuration from ~/.sdlc/sdlc-local.properties.

~ is your home directory: Windows: C:\Users\YourName\.sdlc\  |  macOS: /Users/YourName/.sdlc/  |  Linux: /home/YourName/.sdlc/

Create the directory:

# macOS / Linux
mkdir -p ~/.sdlc

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.sdlc"

Open the file in a text editor:

# macOS / Linux
nano ~/.sdlc/sdlc-local.properties

# Windows (PowerShell)
notepad "$env:USERPROFILE\.sdlc\sdlc-local.properties"

Paste the following, replacing the placeholder with your real key:

# Anthropic key:
llm.anthropicApiKey=sk-ant-YOUR-KEY-HERE

# OpenAI key (alternative):
# llm.openAiApiKey=sk-YOUR-KEY-HERE

Save and close. Verify the file was created:

# macOS / Linux
cat ~/.sdlc/sdlc-local.properties

# Windows
type "$env:USERPROFILE\.sdlc\sdlc-local.properties"

You should see your key printed. If you see "No such file or directory", the file was not saved to the right place — check the path, including the leading dot in .sdlc.

Step 7 — Run your first pipeline

You need a software project on your machine (Spring Boot, Gradle, Node.js, or Python with a standard build file). Run with an inline ticket — no Jira required:

# macOS / Linux
java -jar sdlc-orchestrator.jar \
  --ticket-id TEST-1 \
  --title "Add a health check endpoint" \
  --description "Add a GET /health endpoint that returns HTTP 200 with body: ok" \
  --project /path/to/your/project

# Windows (PowerShell — use backtick for line continuation)
java -jar sdlc-orchestrator.jar `
  --ticket-id TEST-1 `
  --title "Add a health check endpoint" `
  --description "Add a GET /health endpoint that returns HTTP 200 with body: ok" `
  --project C:\path\to\your\project

Happy path — what you should see:

[SDLC] Loading ticket TEST-1...
[SDLC] Checkpoint 0 — Clarification
  Interpretation: Add a GET /health endpoint...
  Open questions: none

[SDLC] Scanning project...
[SDLC] Generating execution plan...

============ EXECUTION PLAN ============
Operations:
  1. CREATE HealthController — new REST controller with GET /health
...

Approve this plan? (yes/no):

Type yes and press Enter. The platform generates code and shows you a diff, then asks:

Approve and apply? (yes/no):

Type yes again. The platform applies the files, runs your build, creates a git commit, and writes an audit record.

Failure cases:

Optional — Set up a short sdlc command

The install scripts do this automatically. If you installed manually, here is how to add the sdlc shortcut:

macOS / Linux:

mkdir -p ~/.sdlc/bin
cp sdlc-orchestrator.jar ~/.sdlc/
cat > ~/.sdlc/bin/sdlc <<'EOF'
#!/bin/sh
exec java -jar "$HOME/.sdlc/sdlc-orchestrator.jar" "$@"
EOF
chmod +x ~/.sdlc/bin/sdlc
echo 'export PATH="$HOME/.sdlc/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc   # or: source ~/.zshrc

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.sdlc\bin"
Copy-Item sdlc-orchestrator.jar "$env:USERPROFILE\.sdlc\"
Set-Content -Path "$env:USERPROFILE\.sdlc\bin\sdlc.bat" `
  -Value "@echo off`r`njava -jar `"%USERPROFILE%\.sdlc\sdlc-orchestrator.jar`" %*"
$p = [Environment]::GetEnvironmentVariable("PATH","User")
[Environment]::SetEnvironmentVariable("PATH","$p;$env:USERPROFILE\.sdlc\bin","User")

Open a new terminal and verify with sdlc --version.

Alternative — one-command install scripts

If you prefer a single command that handles everything (Java must already be installed — the scripts check and fail with a clear error if it's missing or too old):

Linux / macOS:

curl -fsSL https://bakalarsoftware.com/dl/install.sh | bash

After the script finishes, activate in your current shell:

export PATH="${HOME}/.sdlc/bin:${PATH}"

Or open a new terminal.

Windows (PowerShell):

irm https://bakalarsoftware.com/dl/install.ps1 | iex

Restart your terminal after the script finishes.

2. Configuration

All configuration lives in ~/.sdlc/sdlc-local.properties. Create this file before your first run.

Minimal configuration (no Jira)

llm.anthropicApiKey=sk-ant-...

This is enough to run the pipeline using --title to provide the ticket inline.

Full configuration example

# ── LLM provider (pick one) ──────────────────────────────────────────────────
llm.anthropicApiKey=sk-ant-...
# llm.openAiApiKey=sk-...
# llm.ollamaBaseUrl=http://localhost:11434   # local embeddings via Ollama

# ── Jira (optional) ──────────────────────────────────────────────────────────
jira.baseUrl=https://yourco.atlassian.net
jira.email=you@yourco.com
jira.apiToken=<your-jira-api-token>

# ── GitHub (optional) ────────────────────────────────────────────────────────
github.token=<your-github-token>           # enables auto PR creation
# github.issuesRepo=owner/repo             # enables GitHub Issues as ticket source

# ── Linear (optional) ────────────────────────────────────────────────────────
# linear.apiKey=<your-linear-key>

# ── Slack notifications (optional) ───────────────────────────────────────────
# slack.webhookUrl=https://hooks.slack.com/services/...

# ── Email notifications (optional) ───────────────────────────────────────────
# smtp.host=smtp.gmail.com
# smtp.port=587
# smtp.username=sender@example.com
# smtp.password=<app-specific-password>
# smtp.to=recipient@example.com

# ── Approver identity (optional) ─────────────────────────────────────────────
# sdlc.approver=Alice Chen
# sdlc.approver.role=senior-engineer

# ── RBAC: require a role for high-risk intents (optional) ────────────────────
# sdlc.require.role.EXECUTION_REQUEST=senior-engineer
# sdlc.require.role.BUG_FIX=engineer

# ── Coverage gate (optional) ─────────────────────────────────────────────────
# sdlc.coverage.minimum=0.80    # pipeline fails if line coverage drops below 80%

# ── Shared audit database for multi-developer teams (optional) ───────────────
# sdlc.db.url=jdbc:sqlite:/shared/drive/sdlc-audit.db

The config file is never committed to source control — it holds credentials. Your .gitignore should exclude sdlc-local.properties and sdlc.properties.

3. Running the Pipeline

Ticket from Jira

sdlc --ticket-id PROJ-42 --project /path/to/your/project

Ticket provided inline (no Jira required)

sdlc --ticket-id PROJ-42 \
     --title "Add GET /api/users endpoint" \
     --description "As a client I need to retrieve all users from the database." \
     --project /path/to/your/project

Other common invocations

# Custom config file
sdlc --ticket-id PROJ-42 --project /path/to/project --config /path/to/sdlc-local.properties

# Force codebase rescan (skip cached index)
sdlc --ticket-id PROJ-42 --project /path/to/project --rescan

# Dry run — see the diff without applying anything
sdlc --ticket-id PROJ-42 --project /path/to/project --dry-run

What happens when you run

The pipeline proceeds through nine stages. At two points it stops and asks you to approve before continuing. Type yes to proceed or no to stop.

Ticket
  → Checkpoint 0   clarify open questions
  → Scan           index the local codebase
  → Plan           RAG + LLM generates structured plan
  → Validate       hard validation gate (automated)
  → Role gate      RBAC check (if configured)
  → Checkpoint 1   you review and approve the plan
  → CodeGen        LLM reads files, writes implementations
  → Checkpoint 2   you review and approve the generated code
  → Apply          files written to disk
  → Verify         compile + test suite runs
  → Commit         branch created, changes committed
  → PR             GitHub PR opened (if github.token configured)
  → Audit          full record written

4. Pipeline Stages Explained

Checkpoint 0 — Clarification

The LLM reads the ticket and produces a technical interpretation of the request, along with any open questions it cannot resolve from the ticket alone. You see this before any code is planned. If the ticket is ambiguous, this is where you catch it.

Scan

The platform indexes your codebase locally — controllers, services, models, dependencies — and builds a vector index for RAG retrieval. The index is cached; subsequent runs skip re-indexing unless you pass --rescan.

Plan generation

The LLM uses RAG to retrieve relevant parts of your codebase and generates a structured execution plan containing:

• A plain-English summary of the overall change
• A list of operations — each with an intent, a rationale, and the files it affects
• Constraints (things that must be true before code is written)
• Validation requirements (things that must be true after code is written)

Validation (hard gate)

An automated validator checks the plan before any human sees it. It verifies all operations have targets, no circular dependencies exist, and all referenced files are present or explicitly new. If validation fails, the pipeline stops immediately. There is no human bypass.

Role gate

If RBAC is configured, the platform checks whether the current approver's role satisfies the requirement for the detected intent type. If the role does not match, the pipeline stops with outcome REJECTED_BY_RBAC. See Section 10.

Checkpoint 1 — Plan review

The full plan is displayed in your terminal. You read it, then approve or reject. Things to look for:

• Does the plan match what the ticket asked for?
• Are the affected files correct?
• Does anything in the plan seem out of scope or risky?

If you reject, the pipeline stops. No code is generated. The rejection is recorded in the audit log.

Code generation

After plan approval, the LLM reads the actual current contents of every affected file and generates complete, working implementations. No stubs. No TODOs. It writes the file as it should look after the change.

Checkpoint 2 — Diff review

The generated code is displayed as a unified diff. You read it, then approve or reject. Things to look for:

• Does the generated code match the plan?
• Are there any issues a reviewer would flag in a PR?
• Is anything unexpected being changed?

If you pass --dry-run, the pipeline stops here without writing anything.

Apply

Generated file contents are written to disk. Nothing is applied before this point.

Verify

The platform runs your build and test suite based on the detected project type:

If the build fails, the pipeline stops with EXECUTION_FAILED. If sdlc.coverage.minimum is configured and coverage falls below the threshold, the pipeline also fails.

Commit, PR, and audit

On success, the platform:

1. Creates a branch named <ticket-id> (e.g., PROJ-42)
2. Commits all generated files with message [PROJ-42] Ticket Title
3. Opens a GitHub PR from that branch to main (if github.token is configured)
4. Writes a full audit record to ~/.sdlc/audit/
5. Transitions the Jira ticket to "In Review" (if Jira is configured)
6. Sends notifications if --notify is passed and Slack/email are configured

5. Project Type Support

The platform auto-detects your project type by looking for these files in the project root:

To override detection:

sdlc --ticket-id PROJ-42 --project /path --project-type python

Accepted values: spring-boot, spring, maven, gradle, node-typescript, node, typescript, ts, nestjs, express, python, py.

To override only the build verifier independently of the scanner:

sdlc --ticket-id PROJ-42 --project /path --build-system gradle

6. Ticket Sources

Jira (default)

Configure jira.baseUrl, jira.email, and jira.apiToken. The platform fetches the ticket automatically.

sdlc --ticket-id PROJ-42 --project /path/to/project

Linear

Set linear.apiKey in your config. The platform auto-detects Linear when the key is present.

sdlc --ticket-id ENG-123 --project /path/to/project
# or explicitly:
sdlc --ticket-id ENG-123 --project /path/to/project --ticket-source linear

GitHub Issues

Set github.token and github.issuesRepo=owner/repo in your config.

sdlc --ticket-id 42 --project /path/to/project
# or explicitly:
sdlc --ticket-id 42 --project /path/to/project --ticket-source github

Manual (no ticket system)

Skip ticket ingestion entirely by providing the ticket inline. No credentials needed.

sdlc --ticket-id LOCAL-1 \
     --title "Refactor UserService to use repository pattern" \
     --description "Extract database calls from UserService into a UserRepository." \
     --project /path/to/project

Auto-detection order

When --ticket-source is not specified, the platform selects in this order: Linear (if linear.apiKey is set) → GitHub Issues (if both github.token and github.issuesRepo are set) → Jira (fallback).

7. Audit Log

Every pipeline run — including rejections, failures, and dry runs — produces a complete audit record.

Location

~/.sdlc/audit/<TICKET-ID>-<YYYYMMDD-HHMMSS>.json

What is recorded

Possible outcomes

Viewing audit records

# List the 20 most recent runs
sdlc --list-audits

# Show the full record for a ticket
sdlc --show-audit PROJ-42

Shared audit database

For multi-developer teams, point all instances at a shared SQLite database:

sdlc.db.url=jdbc:sqlite:/shared/drive/sdlc-audit.db

Audit JSON is written to both the local file and the shared database. The web dashboard can read from either.

8. Web Dashboard

sdlc --serve
# Open http://localhost:7070

List view

Shows all pipeline runs with summary stats (total runs, success rate, average duration, total cost) and a filterable table. Filters: ticket ID search, outcome dropdown, date range.

Detail view

Click any row to open the full audit record: ticket metadata and outcome, approver identities, git branch and commit SHA, PR link, LLM model and cost, code coverage, the full execution plan, and the generated diff file by file.

9. Compliance Reports

SOC2 Type II evidence report

# Single ticket (text)
sdlc --export-report PROJ-42

# Single ticket (PDF)
sdlc --export-pdf-report PROJ-42

# All tickets
sdlc --export-all

# All tickets since a date (PDF)
sdlc --export-all-pdf --since 2026-01-01

HIPAA change management record

sdlc --export-hipaa-report PROJ-42
sdlc --export-hipaa-pdf-report PROJ-42
sdlc --export-all-hipaa
sdlc --export-all-hipaa-pdf --since 2026-01-01

Output location

~/.sdlc/audit/reports/<TICKET-ID>-report.txt
~/.sdlc/audit/reports/<TICKET-ID>-report.pdf
~/.sdlc/audit/reports/<TICKET-ID>-hipaa.txt
~/.sdlc/audit/reports/<TICKET-ID>-hipaa.pdf

10. Role-Based Access Control

RBAC lets you require a specific approver role for certain types of changes. It is checked automatically after plan validation and before the plan is shown to the user.

Configuration

# Declare who is running the platform
sdlc.approver=Alice Chen
sdlc.approver.role=senior-engineer

# Require senior-engineer for new features and endpoints
sdlc.require.role.EXECUTION_REQUEST=senior-engineer

# Require any engineer for bug fixes
sdlc.require.role.BUG_FIX=engineer

Intent types

Behavior

• If no requirement is configured for the detected intent type, any approver can proceed.
• If a requirement exists and the approver's role matches, the pipeline continues.
• If a requirement exists and the approver has no role, or the role does not match, the pipeline stops with REJECTED_BY_RBAC.
• The RBAC check result is recorded in the audit log.

Regardless of RBAC, the audit log always records planApprover and codeApprover. Identity comes from sdlc.approver in config, or falls back to the USER environment variable.

11. Notifications

Configuration

# Slack
slack.webhookUrl=https://hooks.slack.com/services/T.../B.../...

# Email
smtp.host=smtp.gmail.com
smtp.port=587
smtp.username=sender@example.com
smtp.password=<app-specific-password>
smtp.to=recipient@example.com

Enabling notifications

sdlc --ticket-id PROJ-42 --project /path/to/project --notify

What triggers a notification

Notifications are sent for three outcomes only: SUCCESS, EXECUTION_FAILED, and REJECTED_BY_VALIDATION. Rejections by the developer and dry runs do not send notifications.

SDLC Pipeline Result
Ticket:   PROJ-42
Outcome:  SUCCESS
PR:       https://github.com/your-org/your-repo/pull/123
Commit:   abc123def456...
Duration: 45.3s
Est. cost: $0.0234 USD

Notification failures (unreachable webhook, SMTP error) are logged as warnings and do not affect the pipeline outcome.

12. Metrics

sdlc --metrics

Aggregates statistics across all audit records in ~/.sdlc/audit/:

• Total runs — count of all pipeline executions
• Successful — count and percentage of SUCCESS outcomes
• Per-outcome breakdown — count of each failure type
• Average duration — mean wall-clock time across successful runs (seconds)
• LLM models used — how many runs used each model
• Total tokens — aggregate prompt and completion tokens across all runs
• Total cost — sum of estimated LLM costs across all runs (USD)
• Coverage — average and minimum line coverage percentage across successful runs

13. CI/CD Integration

GitHub Actions

A ready-to-use workflow is included at .github/workflows/sdlc-platform.yml. Use --non-interactive to auto-approve both checkpoints — the human review happens in the PR the platform opens.

- name: Run SDLC pipeline
  run: |
    sdlc --ticket-id "${{ env.TICKET_ID }}" --project . --non-interactive
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Exit codes

Jenkins

Run the platform as a shell step. Use --non-interactive and check the exit code. The platform returns 1 on any failure.

14. Docker

Image: ghcr.io/gbakalar/sdlc-platform:latest

Basic run

docker run --rm \
  -v ~/.sdlc:/root/.sdlc \
  -v /path/to/your/project:/project \
  ghcr.io/gbakalar/sdlc-platform:latest \
  --ticket-id PROJ-42 --project /project

With an explicit config path

docker run --rm \
  -v ~/.sdlc:/root/.sdlc \
  -v /path/to/your/project:/project \
  ghcr.io/gbakalar/sdlc-platform:latest \
  --ticket-id PROJ-42 --project /project --config /root/.sdlc/sdlc-local.properties

Volumes

15. CLI Reference

Pipeline

Pipeline control

Audit and history

Compliance reports

Utilities

16. Config Reference

All properties go in ~/.sdlc/sdlc-local.properties unless --config specifies another path.

LLM

Jira

GitHub

Linear

Notifications

Approver and RBAC

Quality and audit

17. Troubleshooting

"could not determine latest release" during install

The install script fetches the latest tag from the GitHub API. Check your internet connection. If you are behind a proxy, set https_proxy before running the script.

Pipeline fails immediately with "config validation failed"

The platform validates the config on startup. Check that at least one LLM key (llm.anthropicApiKey or llm.openAiApiKey) is present, Jira config is complete if Jira is your ticket source, and there are no trailing spaces in property values.

"REJECTED_BY_VALIDATION" on every run

The plan validator found a problem. Check the validationErrors field in the audit record (sdlc --show-audit TICKET-ID). Common causes: ticket description is too vague (add more detail to --description), or the LLM hallucinated a file path (run --rescan to refresh the index).

Build fails after apply

The generated code has a compile or test error. The failureReason field in the audit record has the verifier output. Common causes: project type misdetected (use --project-type to override), or a stale codebase index (try --rescan).

No GitHub PR is created

github.token must be set in config and the local repo must have a main branch and a configured remote. The platform logs a warning and continues if PR creation fails.

Jira ticket not transitioning to "In Review"

The platform looks for a transition named "In Review" in your Jira workflow. If your workflow uses a different name, the transition is skipped and a warning is logged. The pipeline still completes successfully.

Notifications not arriving

• Verify slack.webhookUrl is the full webhook URL including the path.
• For Gmail, use an App Password rather than your account password.
• Check the events array in the audit JSON — it includes notification delivery logs.

Web dashboard shows no data

The dashboard reads from ~/.sdlc/audit/. Confirm that directory contains .json files. If you configured sdlc.db.url, pass the same --config file to --serve so the dashboard knows where the database is.