Skip to content

Commit 43c29cb

Browse files
nripankadas07nripankadas07
committed
Initial SpecForge release
0 parents  commit 43c29cb

28 files changed

Lines changed: 6547 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
verify:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v4
16+
17+
- name: Setup Node
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: 24
21+
cache: npm
22+
23+
- name: Install
24+
run: npm ci
25+
26+
- name: Lint
27+
run: npm run lint
28+
29+
- name: Test
30+
run: npm run test
31+
32+
- name: Build
33+
run: npm run build

‎.github/workflows/pages.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
25+
- name: Setup Node
26+
uses: actions/setup-node@v4
27+
with:
28+
node-version: 24
29+
cache: npm
30+
31+
- name: Install
32+
run: npm ci
33+
34+
- name: Build
35+
run: npm run build
36+
env:
37+
GITHUB_PAGES: true
38+
39+
- name: Configure Pages
40+
uses: actions/configure-pages@v5
41+
42+
- name: Upload artifact
43+
uses: actions/upload-pages-artifact@v4
44+
with:
45+
path: dist
46+
47+
deploy:
48+
environment:
49+
name: github-pages
50+
url: ${{ steps.deployment.outputs.page_url }}
51+
needs: build
52+
runs-on: ubuntu-latest
53+
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
dist
12+
dist-ssr
13+
*.local
14+
15+
# Editor directories and files
16+
.vscode/*
17+
!.vscode/extensions.json
18+
.idea
19+
.DS_Store
20+
*.suo
21+
*.ntvs*
22+
*.njsproj
23+
*.sln
24+
*.sw?

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 SpecForge contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# SpecForge
2+
3+
SpecForge is a local-first workflow studio for turning open-source trend evidence into a spec-driven portfolio project.
4+
5+
It was designed as a GitHub-profile piece: polished enough to demo, technical enough to inspect, and grounded in current high-star project patterns instead of generic app ideas.
6+
7+
## Why This Exists
8+
9+
The highest-signal repositories I verified on 2026-06-13 cluster around four durable ideas:
10+
11+
- Build-your-own learning and technical depth.
12+
- Curated developer knowledge and awesome-list discovery.
13+
- Visual AI workflow builders and agent orchestration.
14+
- Spec-driven development, guardrails, and MCP-style tooling.
15+
16+
SpecForge combines those ideas into a runnable product: pick high-signal inspirations, simulate a spec-first build workflow, inspect confidence and risk, then export a README-ready blueprint.
17+
18+
## Features
19+
20+
- Trend radar backed by a fixed, source-linked dataset of high-star GitHub repositories.
21+
- Repository scoring engine that weighs stars, technical depth, demo appeal, feasibility, moat, and risk.
22+
- Interactive workflow graph with deterministic event simulation.
23+
- Guardrail and evidence toggles that change the ship score and node status.
24+
- Exportable Markdown blueprint for project planning or README drafts.
25+
- Pure TypeScript scoring and workflow modules covered by Vitest tests.
26+
- Responsive dashboard UI with real repository avatars and no API key requirement.
27+
28+
## Tech Stack
29+
30+
- React 19
31+
- TypeScript 6
32+
- Vite 8
33+
- Vitest
34+
- Lucide React
35+
36+
## Quick Start
37+
38+
```bash
39+
npm install
40+
npm run dev
41+
```
42+
43+
Quality gates:
44+
45+
```bash
46+
npm run lint
47+
npm run test
48+
npm run build
49+
```
50+
51+
## Architecture
52+
53+
```text
54+
src/
55+
data/
56+
repositories.ts verified source dataset
57+
lib/
58+
scoring.ts portfolio scoring and ranking logic
59+
workflow.ts deterministic workflow simulator
60+
exporters.ts Markdown export utilities
61+
App.tsx product shell and interaction wiring
62+
App.css dashboard visual system
63+
```
64+
65+
Read more in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
66+
67+
## Research Sources
68+
69+
- GitHub high-star baseline: https://api.github.com/search/repositories?q=stars:%3E100000&sort=stars&order=desc
70+
- GitHub AI repository query: https://api.github.com/search/repositories?q=topic:ai%20stars:%3E20000&sort=stars&order=desc
71+
- GitHub MCP repository query: https://api.github.com/search/repositories?q=topic:mcp%20stars:%3E5000&sort=stars&order=desc
72+
- GitHub Trending: https://github.com/trending
73+
- OSSInsight AI trending: https://ossinsight.io/trending/ai
74+
- Hacker News spec-driven workflow discussion: https://news.ycombinator.com/item?id=48413629
75+
- Hacker News composable agent discussion: https://news.ycombinator.com/item?id=47350516
76+
77+
Details are in [docs/RESEARCH.md](docs/RESEARCH.md).
78+
79+
## Project Standard
80+
81+
SpecForge is intentionally local-first. It does not call LLM APIs, scrape live social media, or require credentials at runtime. The repository data is fixed inside the app so demos are stable, repeatable, and reviewable.
82+
83+
## License
84+
85+
MIT

‎docs/ARCHITECTURE.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Architecture
2+
3+
SpecForge separates product UI from project intelligence so the repository can be evaluated like a real app instead of a static showcase.
4+
5+
## Data Layer
6+
7+
`src/data/repositories.ts` contains a fixed evidence snapshot from 2026-06-13. Each repository signal has:
8+
9+
- identity fields: owner, name, URL, avatar, language, stars
10+
- category fields: agent, automation, education, MCP, research, systems, UI
11+
- source and evidence notes
12+
- normalized project dimensions: social proof, technical depth, demo appeal, feasibility, moat, and risk
13+
14+
The app uses fixed data by design. GitHub profile demos should not break because a rate limit, API schema, or private token changed.
15+
16+
## Scoring Engine
17+
18+
`src/lib/scoring.ts` exposes three core functions:
19+
20+
- `normalizeStars`: log-scales large star counts so one mega-repo does not dominate every result
21+
- `calculateRepoScore`: ranks a single repository by stars plus product fit dimensions
22+
- `calculatePortfolioScore`: scores a selected project thesis across multiple inspirations
23+
24+
This means the UI is not hand-sorted. The project can be extended with new evidence without rewriting presentation logic.
25+
26+
## Workflow Simulator
27+
28+
`src/lib/workflow.ts` converts selected repositories and build options into a deterministic run:
29+
30+
- signal intake
31+
- spec contract
32+
- workflow graph
33+
- guardrails
34+
- build loop
35+
- release kit
36+
37+
Each node has confidence, risk, duration, status, and an output artifact. The run also produces event timeline entries and dashboard metrics.
38+
39+
## Export Boundary
40+
41+
`src/lib/exporters.ts` generates a Markdown blueprint that can be copied or downloaded. This keeps export logic outside React components and makes it testable later.
42+
43+
## UI Composition
44+
45+
`src/App.tsx` is intentionally a single product shell, while core logic lives in modules. The UI includes:
46+
47+
- sidebar navigation
48+
- project score overview
49+
- mode toggles and scope control
50+
- repository radar
51+
- workflow graph canvas
52+
- node inspector and event timeline
53+
- generated blueprint preview
54+
- evidence chain
55+
56+
## Extension Ideas
57+
58+
- Add a GitHub Actions workflow for lint, tests, and build.
59+
- Add a command-line exporter for blueprint generation.
60+
- Add screenshot generation for README assets.
61+
- Add an optional live GitHub fetcher with cached fallback data.
62+
- Add custom scoring profiles for backend, AI, data, and frontend portfolios.

‎docs/RESEARCH.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Research Notes
2+
3+
Research date: 2026-06-13
4+
5+
The goal was to find a project direction that could impress GitHub profile visitors while staying realistic to build well. The scan combined verified GitHub API data with public developer-discussion surfaces.
6+
7+
## What Was Checked
8+
9+
- GitHub API search for repositories above 100,000 stars.
10+
- GitHub API search for AI repositories above 20,000 stars.
11+
- GitHub API search for MCP repositories above 5,000 stars.
12+
- GitHub Trending.
13+
- OSSInsight AI trending.
14+
- Public Hacker News and Reddit discussions around agent workflows, MCP, spec-driven development, and AI automation security.
15+
- Public YouTube search results around 2026 AI GitHub project roundups.
16+
17+
## Strongest Patterns
18+
19+
### Build-Your-Own Learning
20+
21+
`codecrafters-io/build-your-own-x` had 514,816 stars in the verified GitHub API response. This pattern works because it signals technical depth, practical learning, and from-scratch credibility.
22+
23+
### Curated Developer Knowledge
24+
25+
`sindresorhus/awesome`, `awesome-mcp-servers`, and similar lists show that developers star well-organized discovery surfaces. A great profile project should be useful even before someone runs it.
26+
27+
### Visual Workflow Builders
28+
29+
`n8n`, `langflow`, and `dify` show sustained interest in node-based workflow products. They are visually demoable and technically rich, but too large to clone well in a short portfolio build.
30+
31+
### Agent Guardrails And Specs
32+
33+
GitHub's `spec-kit`, MCP-related repositories, and public developer discussions point toward a useful gap: developers want agentic workflows, but they also want inspectable plans, safety boundaries, and repeatable execution.
34+
35+
## Decision
36+
37+
Build SpecForge: a local-first workflow studio that combines the social pull of high-star developer resources with the demo appeal of workflow builders and the engineering seriousness of spec-driven development.
38+
39+
## Source Links
40+
41+
- https://api.github.com/search/repositories?q=stars:%3E100000&sort=stars&order=desc
42+
- https://api.github.com/search/repositories?q=topic:ai%20stars:%3E20000&sort=stars&order=desc
43+
- https://api.github.com/search/repositories?q=topic:mcp%20stars:%3E5000&sort=stars&order=desc
44+
- https://github.com/trending
45+
- https://ossinsight.io/trending/ai
46+
- https://news.ycombinator.com/item?id=48413629
47+
- https://news.ycombinator.com/item?id=47350516

‎docs/SPEC.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Product Spec
2+
3+
## Objective
4+
5+
Build a local-first app that helps a developer turn high-signal open-source trends into a portfolio project brief and executable workflow.
6+
7+
## Primary User
8+
9+
A developer preparing a GitHub profile project who wants evidence, technical credibility, and a polished demo surface.
10+
11+
## Requirements
12+
13+
- Display a ranked radar of high-star open-source inspirations.
14+
- Allow selecting at least two and at most five repository inspirations.
15+
- Compute a project score from the selected evidence set.
16+
- Simulate a spec-driven workflow with visible node status, risk, confidence, and output.
17+
- Provide toggles for evidence and guardrails.
18+
- Provide a scope control that affects the ship score.
19+
- Generate an exportable Markdown blueprint.
20+
- Run without API keys or external runtime services.
21+
- Include automated tests for the scoring and workflow logic.
22+
23+
## Non-Goals
24+
25+
- It is not a live social-media scraper.
26+
- It is not an LLM agent framework.
27+
- It is not a clone of n8n, Langflow, Dify, or any other referenced project.
28+
- It does not make autonomous changes to local files.
29+
30+
## Acceptance Criteria
31+
32+
- `npm run lint` passes.
33+
- `npm run test` passes.
34+
- `npm run build` passes.
35+
- The app remains usable on desktop and mobile widths.
36+
- Exported Markdown includes the selected evidence, milestones, launch criteria, and sources.
37+
38+
## Current Status
39+
40+
Implemented as a React and TypeScript Vite app with a deterministic local simulator.

‎eslint.config.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import js from '@eslint/js'
2+
import globals from 'globals'
3+
import reactHooks from 'eslint-plugin-react-hooks'
4+
import reactRefresh from 'eslint-plugin-react-refresh'
5+
import tseslint from 'typescript-eslint'
6+
import { defineConfig, globalIgnores } from 'eslint/config'
7+
8+
export default defineConfig([
9+
globalIgnores(['dist']),
10+
{
11+
files: ['**/*.{ts,tsx}'],
12+
extends: [
13+
js.configs.recommended,
14+
tseslint.configs.recommended,
15+
reactHooks.configs.flat.recommended,
16+
reactRefresh.configs.vite,
17+
],
18+
languageOptions: {
19+
globals: globals.browser,
20+
},
21+
},
22+
])

0 commit comments

Comments
 (0)