Skip to content

Commit c67cf10

Browse files
phil-man-git-hubphil-man-git-hub
committed
docs(idd): add and link AI workflow steps, to-do template, and update comprehension guide
1 parent da7dae0 commit c67cf10

File tree

4 files changed

+230
-7
lines changed

4 files changed

+230
-7
lines changed

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,15 @@
2323

2424
-------------------------------------------------------------------------------
2525

26+
## 🚀 Issue-Driven Development & AI Workflow
27+
28+
For standardized, automated, and sustainable GitHub Issue management, see:
29+
**[GitHub Issue AI Workflow Steps](docs/idd/issues/github-issue-ai-workflow-steps.md)**
30+
31+
This guide details the AI-driven workflow, templates, and automation for maintainers, contributors, and onboarding.
32+
33+
-------------------------------------------------------------------------------
34+
2635
## Introduction
2736

2837
LOGIK-PROJEKT is a toolkit designed for the creation, business continuity and lifecycle management of Digital Content Creation (DCC) projekts.

‎docs/idd/ai-comprehension.md‎

Lines changed: 48 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -130,13 +130,54 @@ gh workflow run auto-label.yml --repo phil-man-git-hub/LOGIK-PROJEKT-DEV
130130

131131
## Recommended Next Actions
132132

133-
1. Run the label-sync script in dry-run and then apply to the repository if mapping is correct.
134-
2. Run the issue→TO-DO sync script in dry-run and inspect generated `TO-DO.md` diffs; if the auto-sync markers are missing, add them as documented.
135-
3. Add two small unit tests in `tests/idd/`:
136-
- `test_sync_issues_happy_path.py` — simulate two issues and assert generated TO-DO content contains them.
137-
- `test_label_sync_empty.py` — simulate empty labels file and assert script exits gracefully.
138-
4. Add a short `CONTRIBUTING.md` entry pointing to `docs/idd/guides/guide-best-practices.md` and `docs/idd/ai-comprehension.md` for future contributors.
139-
5. Optionally wire a small CI job that runs `python3 .github/scripts/sync_labels.py --dry-run` on PRs modifying `.github/labels.yml`.
133+
134+
---
135+
136+
## Crucial IDD Workflow Information
137+
138+
## See also: [GitHub Issue AI Workflow Steps](github-issue-ai-workflow-steps.md)
139+
140+
### Generic To-Do Phases Template
141+
- The file `docs/idd/issues/github-issue-to-do-template.json` defines standard phases and tasks for every GitHub Issue to-do file.
142+
- Automation scripts read this template and inject the phases/tasks into each new issue’s to-do file (e.g., `docs/idd/issues/issue-XX/step-51-to-do/README.md`).
143+
- This ensures every issue starts with a consistent, actionable workflow and enables easy updates to the process by editing the template.
144+
145+
#### Example Usage in Automation
146+
1. When a new issue is scaffolded, the script loads `github-issue-to-do-template.json`.
147+
2. The script generates a markdown checklist for the issue’s to-do file, replacing placeholders (like `<issue-number>`) as needed.
148+
3. Contributors and AI agents follow these phases for every issue, ensuring process consistency and traceability.
149+
150+
#### Template Structure
151+
See [`github-issue-to-do-template.json`](github-issue-to-do-template.json) for the current phases and tasks.
152+
153+
#### Issue Directory Tree Template
154+
For Phase 5 and directory scaffolding, see [`github-issue-tree-template.json`](github-issue-tree-template.json) for the standard issue directory and file structure.
155+
156+
### Issue Draft Storage
157+
- Drafts for new GitHub Issues are stored in `docs/idd/issues/drafts/` (e.g., `ISSUE-001-add-idd-workflow.md`).
158+
- This enables collaborative editing and review before publishing the issue on GitHub.
159+
160+
### Procedures After GitHub Issue Creation
161+
- After an issue is created, contributors:
162+
- Create a related branch (e.g., `issue-001-add-idd-workflow`).
163+
- Link the branch and PR to the GitHub Issue using references like “Closes #1”.
164+
- Scaffold a directory in `docs/idd/issues/issue-<number>/` for the new issue.
165+
166+
### Creation of Subdirectories and Documents
167+
- Each issue directory contains subdirectories for workflow steps:
168+
- `step-01-feature-type/`, `step-11-research/`, `step-21-insight/`, `step-31-cognition/`, `step-41-how-to/`, `step-51-to-do/`, `step-61-memory/`
169+
- Each step contains a README or markdown file for documentation and tracking.
170+
171+
### Automated Steps to Populate Documents
172+
- Scripts and workflows scaffold the directory and populate files with templates and required metadata.
173+
- Automation fills in initial context, links to the GitHub issue, and sets up placeholders for research, insights, and to-dos.
174+
175+
### Documentation of Memories and Decisions Before Final Commit
176+
- The `step-61-memory/` subdirectory (e.g., `issue-001-memory.md`) is used to record decisions, context, and session history.
177+
- Contributors and AI agents document key choices, rationale, and outcomes before the final commit and PR.
178+
- This ensures traceability and context preservation for future work and reviews.
179+
180+
---
140181

141182
---
142183

‎docs/idd/issues/github-issue-ai-workflow-steps.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
2+
# GitHub Issue AI Workflow Steps
3+
4+
## Introduction
5+
6+
This document describes the standardized, AI-driven workflow steps for managing GitHub Issues in LOGIK-PROJEKT-DEV. It is designed for maintainers, contributors, and AI agents to ensure every issue follows a consistent, actionable process from draft to completion.
7+
8+
---
9+
10+
## Table of Contents
11+
1. [Introduction](#introduction)
12+
2. [LLM-Assisted Issue Creation Note](#llm-assisted-issue-creation-note)
13+
3. [Example: LLM-Assisted GitHub Issue Creation](#example-llm-assisted-github-issue-creation)
14+
4. [Workflow Overview](#workflow-overview)
15+
5. [Sustainability Interpretation](#sustainability-interpretation)
16+
6. [Next Steps](#next-steps)
17+
18+
---
19+
20+
## LLM-Assisted Issue Creation Note
21+
22+
> **Note:** Users can prompt a large language model (LLM) to "Create GitHub Issue" and enter into a conversation about the nature of the Issue. This allows the LLM to rationalize user desires and generate GitHub Issues that are conventional, concise, and comprehensive, improving both clarity and workflow hygiene.
23+
24+
[Back to TOC](#table-of-contents)
25+
26+
---
27+
28+
## Example: LLM-Assisted GitHub Issue Creation
29+
30+
**User:** Create GitHub Issue for automating desktop app creation for Flame 2027.0.0.
31+
32+
**LLM:** Can you clarify the platforms and expected user experience? Should the automation support both macOS and Linux, and include desktop entry creation?
33+
34+
**User:** Yes, support both platforms. Automate .app and .desktop file creation, and ensure the Python interpreter is detected automatically.
35+
36+
**LLM:** Thank you! Here is a conventional, concise, and comprehensive GitHub Issue:
37+
38+
---
39+
**Title:** [FEATURE] Automate desktop app creation for Flame 2027.0.0 (#42)
40+
41+
**Description:**
42+
Automate the creation of desktop application launchers for LOGIK-PROJEKT on both macOS and Linux. The workflow should:
43+
- Detect the Autodesk Python interpreter automatically
44+
- Generate `.app` bundles for macOS and `.desktop` entries for Linux
45+
- Copy icons and set up Info.plist and shell scripts
46+
- Ensure cross-platform compatibility and robust error handling
47+
48+
**Checklist:**
49+
- [ ] Supports macOS and Linux
50+
- [ ] Detects Python interpreter
51+
- [ ] Creates `.app` and `.desktop` files
52+
- [ ] Copies icons and sets metadata
53+
- [ ] Validates automation with tests
54+
55+
**Linked Issue:** Closes #42
56+
---
57+
58+
This conversational approach allows the LLM to rationalize user desires and generate issues that are conventional, concise, and comprehensive.
59+
60+
[Back to TOC](#table-of-contents)
61+
62+
---
63+
64+
## Workflow Overview
65+
66+
1. **Draft Creation**
67+
- Store initial issue drafts in [`docs/idd/issues/drafts/`](../issues/drafts/) for collaborative editing.
68+
69+
2. **Issue Publication**
70+
- Publish the issue on GitHub using a template from [`.github/ISSUE_TEMPLATE/`](../../../.github/ISSUE_TEMPLATE/).
71+
- Assign labels and link related documentation.
72+
73+
3. **Branch & Directory Setup**
74+
- Create a related branch (e.g., `issue-XX-description`).
75+
- Scaffold the issue directory: [`docs/idd/issues/issue-XX/`](../issues/).
76+
- Link branch and PR to the GitHub Issue (e.g., “Closes #XX”).
77+
78+
4. **To-Do Phases Injection**
79+
- Automation reads [`github-issue-to-do-template.json`](github-issue-to-do-template.json) and injects generic phases/tasks into [`step-51-to-do/README.md`](step-51-to-do/README.md).
80+
- Phases include: Feature Definition, Research, Insight, Implementation, Review, Memory, Finalization.
81+
82+
5. **Subdirectory & Document Creation**
83+
- Automation reads [`github-issue-tree-template.json`](github-issue-tree-template.json) to scaffold the standard subdirectories and files for each workflow step.
84+
- Typical structure includes:
85+
- [`step-01-feature-type/`](step-01-feature-type/), [`step-11-research/`](step-11-research/), [`step-21-insight/`](step-21-insight/), [`step-31-cognition/`](step-31-cognition/), [`step-41-how-to/`](step-41-how-to/), [`step-51-to-do/`](step-51-to-do/), [`step-61-memory/`](step-61-memory/)
86+
- Each subdirectory is populated with a README or markdown file as defined in the template.
87+
88+
6. **Automated Population & Updates**
89+
- Scripts fill in initial context, metadata, and placeholders.
90+
- Automation updates to-do checklists, session logs, and decision records as work progresses.
91+
92+
7. **Memory & Decision Documentation**
93+
- Use [`step-61-memory/`](step-61-memory/) to record key decisions, rationale, and session history before final commit.
94+
95+
8. **Finalization & PR**
96+
- Prepare PR with correct issue linking.
97+
- Ensure all automation checks and documentation are complete.
98+
99+
[Back to TOC](#table-of-contents)
100+
101+
---
102+
103+
## Sustainability Interpretation
104+
105+
- **Consistency:** Every issue follows the same phases and directory structure, reducing confusion and onboarding time.
106+
- **Automation:** Scripts and workflows handle repetitive setup, updates, and documentation, minimizing manual effort.
107+
- **Traceability:** All work, decisions, and context are captured in dedicated files and directories, ensuring future maintainers and AI agents can understand the history.
108+
- **Extensibility:** The template and workflow can be updated centrally (e.g., editing `github-issue-to-do-template.json`), propagating improvements to all future issues.
109+
- **Transparency:** Human-readable documentation and machine-readable templates make the process clear for both contributors and automation.
110+
- **Reviewability:** Each phase and step is documented, making it easy to audit progress, review work, and ensure nothing is missed.
111+
112+
[Back to TOC](#table-of-contents)
113+
114+
---
115+
116+
## Next Steps
117+
118+
- Integrate this workflow into onboarding and contribution guides.
119+
- Periodically review and update the template and documentation for improvements.
120+
- Monitor automation for reliability and adjust as needed.

‎docs/idd/issues/github-issue-to-do-template.json‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
{
2+
"phases": [
3+
{
4+
"name": "Feature/Task Definition",
5+
"tasks": [
6+
"Clarify scope and requirements",
7+
"Link to related documentation and drafts"
8+
]
9+
},
10+
{
11+
"name": "Research & Discovery",
12+
"tasks": [
13+
"Gather background information",
14+
"Identify dependencies and blockers"
15+
]
16+
},
17+
{
18+
"name": "Insight & Planning",
19+
"tasks": [
20+
"Summarize findings",
21+
"Outline solution or implementation steps"
22+
]
23+
},
24+
{
25+
"name": "Implementation",
26+
"tasks": [
27+
"Develop code, scripts, or configuration",
28+
"Write tests and validation scripts"
29+
]
30+
},
31+
{
32+
"name": "Review & Documentation",
33+
"tasks": [
34+
"Peer review changes",
35+
"Update documentation and changelogs"
36+
]
37+
},
38+
{
39+
"name": "Memory & Decision Log",
40+
"tasks": [
41+
"Record key decisions and rationale",
42+
"Update AI context and session history"
43+
]
44+
},
45+
{
46+
"name": "Finalization",
47+
"tasks": [
48+
"Prepare PR with 'Closes #<issue-number>'",
49+
"Ensure all automation checks pass"
50+
]
51+
}
52+
]
53+
}

0 commit comments

Comments
 (0)