spec-kit Piranha Server Brownfield Demo

This project demonstrates a brownfield AI-assisted development workflow using spec-kit on an existing Jakarta EE runtime. Starting from a cloned open-source repository with ~420,000 lines of Java, XML, JSP, HTML, and config files across 180 Maven modules, a new management console feature was added entirely through structured agents in GitHub Copilot Chat. The steps below document exactly what was done — you can follow the same process to extend your own projects.

Note on the workflow: There was no pre-existing spec-kit constitution or formal specifications in this project. The constitution was generated from scratch by having the agent analyze the existing codebase. The feature specification is not an elaborate formal document — it is a short natural-language prompt describing the desired outcome, as you will see below.

Acknowledgements

This project is built on top of Piranha, an open-source Jakarta EE and MicroProfile runtime created and maintained by the Eclipse EE4J community. All credit for the original runtime architecture, feature set, and implementation belongs to the Piranha contributors. Please visit the original repository to learn more, contribute, or show your appreciation.

---

Prerequisites

• uv — Python package manager used to install spec-kit
• VS Code with the GitHub Copilot extension

---

Step 1 — Clone the project

git clone https://github.com/eclipse-ee4j/piranha.git
cd piranha

This was cloned at commit 2f1bb0765b1294e366d911ac2fc5357c3f514425.

Step 2 — Install spec-kit

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Step 3 — Initialize the project

specify init . --integration copilot --integration-options="--skills"

This scaffolded the spec-kit structure and installed the Copilot skills (slash commands).

Step 4 — Open in VS Code

code .

Step 5 — How to invoke a spec-kit command

All spec-kit commands are installed as Copilot skills. Open Copilot Chat and type the slash command (for example /speckit-constitution) directly into the chat input to invoke it.

The commands available are:

Command	Purpose
/speckit-constitution	Define project-wide principles and governance
/speckit-specify	Generate a feature specification from a description
/speckit-clarify	Ask targeted questions to tighten an existing spec
/speckit-plan	Produce a technical design and implementation plan
/speckit-analyze	Check consistency across spec, plan, and tasks
/speckit-tasks	Generate a dependency-ordered task list
/speckit-checklist	Produce a custom quality checklist
/speckit-implement	Execute tasks from tasks.md
/speckit-converge	Assess the codebase and append remaining work as tasks
/speckit-taskstoissues	Convert tasks into GitHub Issues

---

Step 6 — Establish project principles

The /speckit-constitution command was invoked with:

As this is a pre-existing brownfield project I need you to analyze the
codebase exhaustive and in-depth. Do NOT skim over but use multiple
iterations to do a deep analysis and use or create principles focused on
code quality, testing standards, user experience consistency, and
performance requirements. Include governance for how these principles
should guide technical decisions and implementation choices.

This created .specify/memory/constitution.md, which all subsequent agents respected. Because this is a brownfield project with no prior constitution, the agent derived all principles directly from the existing codebase — no manual pre-authoring was required.

---

Feature — Server Admin Console

Step 7 — Write the feature specification

The /speckit-specify command was invoked with:

I want to be able to manage the applications hosted using the Piranha
Server distribution and as such I need a web application for that I can
use to manage it. It must be password protected and allow starting /
stopping a web application, show JVM memory statistics, and make it
possible to deploy and undeploy a web application.

Step 8 — Create the implementation plan

The /speckit-plan command was invoked with:

Store the web application module you will use to create the WAR project in
webapp/server-admin. Use JSP pages for the UI so we have minimal web
dependencies. Piranha Server already has JSP available as part of its
runtime stack. Use or create a global ServerPiranha or something similar
to be able to interact with the Piranha Server distribution. When creating
the module make the Piranha Server API a provided dependency.

Step 9 — Clarify a naming concern

After reviewing the plan, the proposed ServerPiranha class would be placed in the multi-module Piranha module, which violated existing naming conventions. The /speckit-clarify command was invoked to address this:

Should we call it MultiPiranhaSingleton though?

The naming was resolved and a follow-up was sent to lock in the design decision:

OK capture the getInstance() in the plan

Step 10 — Generate the task list

The /speckit-tasks command was invoked with:

Execute

Step 11 — Implement

The /speckit-implement command was invoked with:

Execute. Remember to test the admin console you WILL need to use Piranha
Server and put the WAR file into the webapps directory so it is available
upon startup!

---

Result

A brownfield Jakarta EE runtime extended with a password-protected Server Admin Console — built through structured agent workflows without manual scaffolding. The console provides application lifecycle management (start/stop/deploy/undeploy) and JVM memory monitoring for applications hosted on Piranha Server.