humanmd 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- humanmd/__init__.py +1 -0
- humanmd/__main__.py +3 -0
- humanmd/cli.py +149 -0
- humanmd/templates/exploration.md +34 -0
- humanmd/templates/minimal.md +23 -0
- humanmd/templates/research.md +37 -0
- humanmd/templates/software.md +34 -0
- humanmd-0.1.0.dist-info/METADATA +218 -0
- humanmd-0.1.0.dist-info/RECORD +12 -0
- humanmd-0.1.0.dist-info/WHEEL +4 -0
- humanmd-0.1.0.dist-info/entry_points.txt +2 -0
- humanmd-0.1.0.dist-info/licenses/LICENSE +21 -0
humanmd/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""A small, offline initializer for human-owned project intent."""
|
humanmd/__main__.py
ADDED
humanmd/cli.py
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
"""Initialize HUMAN.md without generating or replacing human intent."""
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
from importlib import metadata, resources
|
|
5
|
+
import os
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
import shutil
|
|
8
|
+
import sys
|
|
9
|
+
import textwrap
|
|
10
|
+
|
|
11
|
+
TEMPLATES = {
|
|
12
|
+
"minimal": "A short starting point for any project.",
|
|
13
|
+
"research": "Questions, hypotheses, and evaluation criteria.",
|
|
14
|
+
"software": "Problems, users, constraints, and success criteria.",
|
|
15
|
+
"exploration": "Early ideas, assumptions, and experiments.",
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def package_version():
|
|
20
|
+
try:
|
|
21
|
+
return metadata.version("humanmd")
|
|
22
|
+
except metadata.PackageNotFoundError:
|
|
23
|
+
return "unknown (install humanmd to read its package version)"
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def print_success(target, template):
|
|
27
|
+
"""Present the next step without adding terminal controls to redirected output."""
|
|
28
|
+
terminal = sys.stdout.isatty() and os.environ.get("TERM") != "dumb"
|
|
29
|
+
color = terminal and "NO_COLOR" not in os.environ
|
|
30
|
+
if os.name == "nt" and not os.environ.get("WT_SESSION"):
|
|
31
|
+
color = False
|
|
32
|
+
encoding = sys.stdout.encoding or "utf-8"
|
|
33
|
+
try:
|
|
34
|
+
"╭─╮│╰╯✓".encode(encoding)
|
|
35
|
+
use_unicode = terminal
|
|
36
|
+
except (UnicodeEncodeError, LookupError):
|
|
37
|
+
use_unicode = False
|
|
38
|
+
width = max(20, min(shutil.get_terminal_size().columns - 4, 72))
|
|
39
|
+
|
|
40
|
+
def paint(value, style):
|
|
41
|
+
return f"\033[{style}m{value}\033[0m" if color else value
|
|
42
|
+
|
|
43
|
+
def write(value="", style=None):
|
|
44
|
+
# Keep paths printable even when a terminal has a legacy encoding.
|
|
45
|
+
value = value.encode(encoding, errors="backslashreplace").decode(encoding)
|
|
46
|
+
if style and value:
|
|
47
|
+
value = paint(value, style)
|
|
48
|
+
print(" " + value if value else "")
|
|
49
|
+
|
|
50
|
+
def wrapped(value, style=None):
|
|
51
|
+
for line in textwrap.wrap(value, width=width):
|
|
52
|
+
write(line, style)
|
|
53
|
+
|
|
54
|
+
tagline = "Code is getting cheaper. Thinking isn't."
|
|
55
|
+
write()
|
|
56
|
+
if terminal and width >= 46:
|
|
57
|
+
inner = width - 4
|
|
58
|
+
left, horizontal, right, side, bottom_left, bottom_right = (
|
|
59
|
+
("╭", "─", "╮", "│", "╰", "╯") if use_unicode
|
|
60
|
+
else ("+", "-", "+", "|", "+", "+")
|
|
61
|
+
)
|
|
62
|
+
write(left + horizontal * (width - 2) + right, "36")
|
|
63
|
+
for label in ("HUMAN.md", tagline):
|
|
64
|
+
write(side + " " + label.ljust(inner) + " " + side, "1;36")
|
|
65
|
+
write(bottom_left + horizontal * (width - 2) + bottom_right, "36")
|
|
66
|
+
else:
|
|
67
|
+
write("HUMAN.md", "1;36")
|
|
68
|
+
wrapped(tagline)
|
|
69
|
+
write()
|
|
70
|
+
wrapped(f"{'✓' if use_unicode else '+'} Created HUMAN.md ({template})", "1;32")
|
|
71
|
+
wrapped(f"Location: {target}", "2")
|
|
72
|
+
write()
|
|
73
|
+
write("BEFORE YOU BUILD", "1")
|
|
74
|
+
for step, instruction in enumerate((
|
|
75
|
+
"Open HUMAN.md and write why this project exists.",
|
|
76
|
+
"Define success, or what you want to learn.",
|
|
77
|
+
"Ask your agent to read it before implementation.",
|
|
78
|
+
), start=1):
|
|
79
|
+
lines = textwrap.wrap(instruction, width=width - 4)
|
|
80
|
+
write(f"{step:02} {lines[0]}", "36")
|
|
81
|
+
for line in lines[1:]:
|
|
82
|
+
write(" " + line)
|
|
83
|
+
write()
|
|
84
|
+
wrapped("AI can propose. Humans decide.", "2")
|
|
85
|
+
write()
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def initialize(path, template):
|
|
89
|
+
"""Create a template exclusively; leave existing directory entries intact."""
|
|
90
|
+
try:
|
|
91
|
+
directory = Path(path).expanduser().resolve()
|
|
92
|
+
if not directory.is_dir():
|
|
93
|
+
print(
|
|
94
|
+
f"Error: target directory does not exist or is not a directory: {directory}",
|
|
95
|
+
file=sys.stderr,
|
|
96
|
+
)
|
|
97
|
+
return 1
|
|
98
|
+
if template not in TEMPLATES:
|
|
99
|
+
print(
|
|
100
|
+
f"Error: invalid template {template!r}. Choose from: {', '.join(TEMPLATES)}",
|
|
101
|
+
file=sys.stderr,
|
|
102
|
+
)
|
|
103
|
+
return 1
|
|
104
|
+
content = (
|
|
105
|
+
resources.files("humanmd")
|
|
106
|
+
.joinpath("templates")
|
|
107
|
+
.joinpath(f"{template}.md")
|
|
108
|
+
.read_text(encoding="utf-8")
|
|
109
|
+
)
|
|
110
|
+
target = directory / "HUMAN.md"
|
|
111
|
+
# Windows can follow a dangling symlink even in exclusive-open mode,
|
|
112
|
+
# and reports existing directories as permission errors. Inspect the
|
|
113
|
+
# directory entry itself before opening; keep exclusive creation to
|
|
114
|
+
# protect against another initializer creating a regular file meanwhile.
|
|
115
|
+
try:
|
|
116
|
+
target.lstat()
|
|
117
|
+
except FileNotFoundError:
|
|
118
|
+
pass
|
|
119
|
+
else:
|
|
120
|
+
raise FileExistsError
|
|
121
|
+
with target.open("x", encoding="utf-8", newline="\n") as stream:
|
|
122
|
+
stream.write(content)
|
|
123
|
+
except FileExistsError:
|
|
124
|
+
print("HUMAN.md already exists.\nNothing was changed.", file=sys.stderr)
|
|
125
|
+
return 1
|
|
126
|
+
except (OSError, RuntimeError) as error:
|
|
127
|
+
print(f"Error: could not initialize HUMAN.md: {error}", file=sys.stderr)
|
|
128
|
+
return 1
|
|
129
|
+
print_success(target, template)
|
|
130
|
+
return 0
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def main(argv=None):
|
|
134
|
+
parser = argparse.ArgumentParser(description="Give human intent a home. Initialize a HUMAN.md template offline.")
|
|
135
|
+
parser.add_argument("--version", action="version", version=package_version())
|
|
136
|
+
commands = parser.add_subparsers(dest="command")
|
|
137
|
+
init = commands.add_parser("init", help="Create HUMAN.md without overwriting existing work.")
|
|
138
|
+
init.add_argument("-t", "--template", choices=TEMPLATES, default="minimal", help="Template to use (default: minimal).")
|
|
139
|
+
init.add_argument("--path", default=".", help="Existing target directory (default: current directory).")
|
|
140
|
+
commands.add_parser("templates", help="List the four bundled templates.")
|
|
141
|
+
args = parser.parse_args(argv)
|
|
142
|
+
if args.command == "init":
|
|
143
|
+
return initialize(args.path, args.template)
|
|
144
|
+
if args.command == "templates":
|
|
145
|
+
for name, description in TEMPLATES.items():
|
|
146
|
+
print(f"{name:12} {description}")
|
|
147
|
+
return 0
|
|
148
|
+
parser.print_help()
|
|
149
|
+
return 0
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# HUMAN.md
|
|
2
|
+
|
|
3
|
+
Uncertainty is welcome. Leave questions open until you have evidence.
|
|
4
|
+
|
|
5
|
+
## Creator's note (optional)
|
|
6
|
+
In your own words, why did you start this project, and why does it matter to you? Leave blank or remove this section if you prefer.
|
|
7
|
+
|
|
8
|
+
## Observation
|
|
9
|
+
What caught our attention?
|
|
10
|
+
|
|
11
|
+
## Initial Idea
|
|
12
|
+
What might be worth exploring, and why?
|
|
13
|
+
|
|
14
|
+
## Assumptions
|
|
15
|
+
What are we taking for granted?
|
|
16
|
+
|
|
17
|
+
## Open Questions
|
|
18
|
+
What do we not yet understand?
|
|
19
|
+
|
|
20
|
+
## Experiments
|
|
21
|
+
What small experiments could challenge our assumptions?
|
|
22
|
+
|
|
23
|
+
## Learnings
|
|
24
|
+
What have we learned? Leave blank until there is evidence.
|
|
25
|
+
|
|
26
|
+
## Decision Log
|
|
27
|
+
|
|
28
|
+
### YYYY-MM-DD — Initial Intent
|
|
29
|
+
|
|
30
|
+
**Decision:**
|
|
31
|
+
|
|
32
|
+
**Reason:**
|
|
33
|
+
|
|
34
|
+
**Impact:**
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# HUMAN.md
|
|
2
|
+
|
|
3
|
+
## Creator's note (optional)
|
|
4
|
+
In your own words, why did you start this project, and why does it matter to you? Leave blank or remove this section if you prefer.
|
|
5
|
+
|
|
6
|
+
## Why?
|
|
7
|
+
Why does this project exist?
|
|
8
|
+
|
|
9
|
+
## What?
|
|
10
|
+
What are we trying to achieve?
|
|
11
|
+
|
|
12
|
+
## How will we know?
|
|
13
|
+
What would success look like?
|
|
14
|
+
|
|
15
|
+
## Decision Log
|
|
16
|
+
|
|
17
|
+
### YYYY-MM-DD — Initial Intent
|
|
18
|
+
|
|
19
|
+
**Decision:**
|
|
20
|
+
|
|
21
|
+
**Reason:**
|
|
22
|
+
|
|
23
|
+
**Impact:**
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# HUMAN.md
|
|
2
|
+
|
|
3
|
+
Partial answers and open questions are welcome.
|
|
4
|
+
|
|
5
|
+
## Creator's note (optional)
|
|
6
|
+
In your own words, why did you start this project, and why does it matter to you? Leave blank or remove this section if you prefer.
|
|
7
|
+
|
|
8
|
+
## Description
|
|
9
|
+
What are we studying, and why does it matter?
|
|
10
|
+
|
|
11
|
+
## Research Question
|
|
12
|
+
What specific question do we want to answer?
|
|
13
|
+
|
|
14
|
+
## Hypothesis
|
|
15
|
+
What falsifiable prediction are we making? What would refute it?
|
|
16
|
+
|
|
17
|
+
## Data
|
|
18
|
+
What data will we use, and what limitations or permissions apply?
|
|
19
|
+
|
|
20
|
+
## Implementation
|
|
21
|
+
What approach will help us investigate the question?
|
|
22
|
+
|
|
23
|
+
## Analysis
|
|
24
|
+
What evaluation criteria will we define before interpreting results?
|
|
25
|
+
|
|
26
|
+
## Expected Results
|
|
27
|
+
What do we expect, and how would contrary results change our thinking?
|
|
28
|
+
|
|
29
|
+
## Decision Log
|
|
30
|
+
|
|
31
|
+
### YYYY-MM-DD — Initial Intent
|
|
32
|
+
|
|
33
|
+
**Decision:**
|
|
34
|
+
|
|
35
|
+
**Reason:**
|
|
36
|
+
|
|
37
|
+
**Impact:**
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# HUMAN.md
|
|
2
|
+
|
|
3
|
+
Partial answers and open questions are welcome.
|
|
4
|
+
|
|
5
|
+
## Creator's note (optional)
|
|
6
|
+
In your own words, why did you start this project, and why does it matter to you? Leave blank or remove this section if you prefer.
|
|
7
|
+
|
|
8
|
+
## Problem
|
|
9
|
+
What problem deserves solving?
|
|
10
|
+
|
|
11
|
+
## Motivation
|
|
12
|
+
Why does solving it matter to us?
|
|
13
|
+
|
|
14
|
+
## Target Users
|
|
15
|
+
Who needs this, and what do they need to accomplish?
|
|
16
|
+
|
|
17
|
+
## Proposed Approach
|
|
18
|
+
What approach do we believe will help, and why?
|
|
19
|
+
|
|
20
|
+
## Constraints
|
|
21
|
+
What boundaries or tradeoffs must we respect?
|
|
22
|
+
|
|
23
|
+
## Success Criteria
|
|
24
|
+
What observable outcomes would make this useful?
|
|
25
|
+
|
|
26
|
+
## Decision Log
|
|
27
|
+
|
|
28
|
+
### YYYY-MM-DD — Initial Intent
|
|
29
|
+
|
|
30
|
+
**Decision:**
|
|
31
|
+
|
|
32
|
+
**Reason:**
|
|
33
|
+
|
|
34
|
+
**Impact:**
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: humanmd
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Initialize human-owned research and software project intent documents from Markdown templates.
|
|
5
|
+
Project-URL: Repository, https://github.com/Kylo1110/HUMANmd
|
|
6
|
+
Project-URL: Issues, https://github.com/Kylo1110/HUMANmd/issues
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: ai,human-intent,markdown,templates
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<img src="https://raw.githubusercontent.com/Kylo1110/HUMANmd/main/docs/assets/humanmd-banner.png" width="100%" alt="HUMAN.md. A pixel-art woman and man, depicted as developers or researchers, collaborate with a friendly robot over a shared intent document.">
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
<p align="center">
|
|
21
|
+
<a href="https://github.com/Kylo1110/HUMANmd/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-teal.svg?style=flat-square" alt="License: MIT"></a>
|
|
22
|
+
<a href="https://github.com/Kylo1110/HUMANmd/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square" alt="Python: 3.10+"></a>
|
|
23
|
+
<a href="https://github.com/Kylo1110/HUMANmd/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/version-0.1.0-orange.svg?style=flat-square" alt="Version: 0.1.0"></a>
|
|
24
|
+
<a href="https://github.com/Kylo1110/HUMANmd/blob/main/docs/cli.md#errors-and-safety"><img src="https://img.shields.io/badge/works-offline-teal.svg?style=flat-square" alt="Works offline"></a>
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
<p align="center">
|
|
28
|
+
<a href="https://github.com/Kylo1110/HUMANmd#get-started">Get started</a> ·
|
|
29
|
+
<a href="https://github.com/Kylo1110/HUMANmd/blob/main/docs/specification.md">Specification</a> ·
|
|
30
|
+
<a href="https://github.com/Kylo1110/HUMANmd/blob/main/docs/agent-integration.md">Agent guidance</a> ·
|
|
31
|
+
<a href="https://github.com/Kylo1110/HUMANmd#contributing">Contribute</a>
|
|
32
|
+
</p>
|
|
33
|
+
|
|
34
|
+
## Code explains how. HUMAN.md explains why.
|
|
35
|
+
|
|
36
|
+
HUMAN.md is an invitation to think deliberately before building, and to keep thinking as a project develops. Ask why the work matters, what you hope to achieve, and which assumptions you want to test. A small, human-owned Markdown file gives the important parts of that reflection a home, so collaborators, AI agents, and your future self can understand how the direction developed.
|
|
37
|
+
|
|
38
|
+
A few honest sentences can be enough. Templates, headings, and Decision Logs are optional: adapt them as the project develops, leave questions open, and add detail when it helps. HUMAN.md keeps the reasoning alongside your code and existing documentation.
|
|
39
|
+
|
|
40
|
+
## A note from the creators
|
|
41
|
+
|
|
42
|
+
In a world that keeps moving faster, we want to make a little room to slow down and collect our thoughts. Take a pen or an iPad, make a cup of coffee or tea, and think about what you want your project to achieve. We hope it can become a small fireplace for you and your team—a place to gather your thoughts, question assumptions, and return as the project develops.
|
|
43
|
+
|
|
44
|
+
**There is no perfect structure to fill in. Give the thinking a place to happen.**
|
|
45
|
+
|
|
46
|
+
Agents can help us explore and challenge ideas, while we remain responsible for directing their work, reviewing the results, and how we use the code. A [recent study of repository-level context files](https://arxiv.org/html/2602.11988v3) found that they did not generally improve coding agents' task success. For us, that's a reminder to focus HUMAN.md on making human intent explicit, rather than adding documentation for its own sake.
|
|
47
|
+
|
|
48
|
+
HUMAN.md is an evolving idea. We don't claim it's a proven solution or the right fit for every project, and we invite you to help shape it. Our [creator's note](https://github.com/Kylo1110/HUMANmd/blob/main/HUMAN.md#a-note-from-the-creator) shares the personal thinking behind the idea.
|
|
49
|
+
|
|
50
|
+
## Before the first line of code
|
|
51
|
+
|
|
52
|
+
**Start with a reason for the next step.**
|
|
53
|
+
|
|
54
|
+
<p align="center">
|
|
55
|
+
<img src="https://raw.githubusercontent.com/Kylo1110/HUMANmd/main/docs/assets/think-before-code.png" width="100%" alt="A blonde woman researcher and a man researcher, wearing lab coats and holding research notes, work with an AI robot through six steps: find the purpose, question assumptions, define success, write HUMAN.md, make a human decision, then build. A return loop from the decision to the questions shows reflection and refinement before proceeding.">
|
|
56
|
+
</p>
|
|
57
|
+
|
|
58
|
+
**Your first step may be an experiment. Write down what you want to learn before asking an agent to build it.**
|
|
59
|
+
|
|
60
|
+
The diagram offers a starting point, with room to revisit questions, assumptions, and intended outcomes. An exhaustive plan isn't required. As you experiment, implement, and maintain the project, explain what you learn and why the approach changes.
|
|
61
|
+
|
|
62
|
+
HUMAN.md follows three simple principles:
|
|
63
|
+
|
|
64
|
+
1. Human ownership. People define the purpose and remain responsible for the work.
|
|
65
|
+
2. Agent awareness. Give agents context to question assumptions and ask before changing direction.
|
|
66
|
+
3. Evolving reasoning. Record meaningful changes in understanding, not every code change.
|
|
67
|
+
|
|
68
|
+
## One file. A different purpose.
|
|
69
|
+
|
|
70
|
+
Your README may already explain why the project exists. HUMAN.md offers a dedicated home when it helps to keep ideas, assumptions, and decisions together. Link to existing explanations rather than duplicating them. These roles can overlap:
|
|
71
|
+
|
|
72
|
+
| File | Purpose |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| `README.md` | What the project does and how to use it. |
|
|
75
|
+
| `AGENTS.md` | How AI agents should work in the project. |
|
|
76
|
+
| `CHANGELOG.md` | What changed in the software. |
|
|
77
|
+
| `HUMAN.md` | Why the project exists, what it aims to achieve, and how its reasoning evolves. |
|
|
78
|
+
|
|
79
|
+
## Get started
|
|
80
|
+
|
|
81
|
+
Use the optional CLI to copy a template, or start writing a Markdown file yourself.
|
|
82
|
+
|
|
83
|
+
### Option 1 — Use the CLI
|
|
84
|
+
|
|
85
|
+
*Release prerequisite: `humanmd` is not currently available on PyPI. These commands apply after publication; until then, use Markdown as described in Option 2.*
|
|
86
|
+
|
|
87
|
+
Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+. Install the CLI, then initialize a file inside your project's existing directory:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
uv tool install humanmd
|
|
91
|
+
humanmd init
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Choose a template:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
humanmd init --template research
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
List templates or get help:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
humanmd templates
|
|
104
|
+
humanmd --help
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The installed CLI works offline, has no runtime dependencies, and never overwrites an existing `HUMAN.md`. The target directory must already exist.
|
|
108
|
+
|
|
109
|
+
**The CLI offers a starting point. You provide the thinking.**
|
|
110
|
+
|
|
111
|
+
### Option 2 — Just use Markdown
|
|
112
|
+
|
|
113
|
+
No installation is needed. Create a `HUMAN.md` in your project root and start writing about its purpose, goals, and assumptions:
|
|
114
|
+
|
|
115
|
+
```markdown
|
|
116
|
+
# HUMAN.md
|
|
117
|
+
|
|
118
|
+
## Why?
|
|
119
|
+
Why does this project exist?
|
|
120
|
+
|
|
121
|
+
## What?
|
|
122
|
+
What are we trying to achieve?
|
|
123
|
+
|
|
124
|
+
## How will we know?
|
|
125
|
+
What would success look like?
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
You can also begin with a Creator's note explaining what brought you to the project. No sections are mandatory; see the [voluntary specification](https://github.com/Kylo1110/HUMANmd/blob/main/docs/specification.md).
|
|
129
|
+
|
|
130
|
+
<details>
|
|
131
|
+
<summary>A small example: organizing research experiments</summary>
|
|
132
|
+
|
|
133
|
+
This fictional example shows the kind of reasoning you might write. Its success criteria are proposed, not measured results.
|
|
134
|
+
|
|
135
|
+
```markdown
|
|
136
|
+
# HUMAN.md
|
|
137
|
+
|
|
138
|
+
## Why?
|
|
139
|
+
Our experiment notes are scattered across folders. We want to understand
|
|
140
|
+
earlier experiments without reconstructing their context from memory.
|
|
141
|
+
|
|
142
|
+
## What?
|
|
143
|
+
A lightweight local tool for researchers to group notes and link artifacts,
|
|
144
|
+
without uploading unpublished data.
|
|
145
|
+
|
|
146
|
+
## How will we know?
|
|
147
|
+
In a trial, a researcher should be able to record an experiment in under
|
|
148
|
+
two minutes and find its purpose, parameters, and artifacts a week later.
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
See the [full software example](https://github.com/Kylo1110/HUMANmd/blob/main/examples/software-project/HUMAN.md) for constraints and an initial decision.
|
|
152
|
+
|
|
153
|
+
</details>
|
|
154
|
+
|
|
155
|
+
## Choose a starting point
|
|
156
|
+
|
|
157
|
+
Different projects begin with different questions.
|
|
158
|
+
|
|
159
|
+
| Template | Best for |
|
|
160
|
+
| --- | --- |
|
|
161
|
+
| [Minimal](https://github.com/Kylo1110/HUMANmd/blob/main/src/humanmd/templates/minimal.md) | Purpose, goals, and success criteria. |
|
|
162
|
+
| [Research](https://github.com/Kylo1110/HUMANmd/blob/main/src/humanmd/templates/research.md) | Research questions, hypotheses, data, and evaluation. |
|
|
163
|
+
| [Software](https://github.com/Kylo1110/HUMANmd/blob/main/src/humanmd/templates/software.md) | Problems, users, constraints, and desired outcomes. |
|
|
164
|
+
| [Exploration](https://github.com/Kylo1110/HUMANmd/blob/main/src/humanmd/templates/exploration.md) | Early ideas, assumptions, and experiments. |
|
|
165
|
+
|
|
166
|
+
All four templates can be adapted and include an optional Creator's note. See the [Creator's note guidance](https://github.com/Kylo1110/HUMANmd/blob/main/docs/specification.md#creators-note-optional). See the fictional [research](https://github.com/Kylo1110/HUMANmd/blob/main/examples/research-project/HUMAN.md) and [software](https://github.com/Kylo1110/HUMANmd/blob/main/examples/software-project/HUMAN.md) examples.
|
|
167
|
+
|
|
168
|
+
## Give your AI agents context
|
|
169
|
+
|
|
170
|
+
Give agents the purpose as well as the task. Add this instruction to your `AGENTS.md` or equivalent agent configuration:
|
|
171
|
+
|
|
172
|
+
> Before implementation, read HUMAN.md. Treat it as the human-owned source of project intent. Use it to guide decisions. If a proposed change conflicts with documented goals or assumptions, ask for human approval. Suggest updates when new findings challenge the original reasoning.
|
|
173
|
+
|
|
174
|
+
HUMAN.md doesn't automatically enforce agent behavior, and the CLI doesn't modify agent instructions. See the [agent integration guide](https://github.com/Kylo1110/HUMANmd/blob/main/docs/agent-integration.md).
|
|
175
|
+
|
|
176
|
+
## When your thinking changes, write it down
|
|
177
|
+
|
|
178
|
+
When evidence challenges an assumption or a better approach emerges, explain what changed and why. You can revise a note, link to an experiment or discussion, or use an optional Decision Log like this:
|
|
179
|
+
|
|
180
|
+
```markdown
|
|
181
|
+
### 2026-11-08 — Markdown first
|
|
182
|
+
|
|
183
|
+
**Decision:** Keep the convention in ordinary Markdown
|
|
184
|
+
and the CLI dependency-free.
|
|
185
|
+
|
|
186
|
+
**Reason:** Intent should remain accessible without
|
|
187
|
+
a service or special tooling.
|
|
188
|
+
|
|
189
|
+
**Impact:** Anyone can adopt HUMAN.md with a single
|
|
190
|
+
file, even without installing the CLI.
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Git preserves revisions; your explanations make the changes in reasoning understandable. Focus on what you learned and why the direction changed, without documenting every task, refactor, or bug fix.
|
|
194
|
+
|
|
195
|
+
## Contributing
|
|
196
|
+
|
|
197
|
+
HUMAN.md is an early open-source convention, and the goal is to keep it simple and useful. Contributions are welcome: improve a template, clarify the documentation, suggest better agent guidance, or share how you're using HUMAN.md. See [CONTRIBUTING.md](https://github.com/Kylo1110/HUMANmd/blob/main/CONTRIBUTING.md) and the [project philosophy](https://github.com/Kylo1110/HUMANmd/blob/main/docs/philosophy.md).
|
|
198
|
+
|
|
199
|
+
For CLI details and release preparation, see the [CLI guide](https://github.com/Kylo1110/HUMANmd/blob/main/docs/cli.md). Licensed under [MIT](https://github.com/Kylo1110/HUMANmd/blob/main/LICENSE).
|
|
200
|
+
|
|
201
|
+
## Thank you
|
|
202
|
+
|
|
203
|
+
Thank you to [@butterpear](https://github.com/butterpear), [@justinw98](https://github.com/justinw98), and [@sinwarmer](https://github.com/sinwarmer) for brainstorming and discussing this idea. Your questions and perspectives helped shape HUMAN.md.
|
|
204
|
+
|
|
205
|
+
<p align="center">
|
|
206
|
+
<img src="https://raw.githubusercontent.com/Kylo1110/HUMANmd/main/docs/assets/humanmd-footer.png" width="640" alt="A woman researcher, man developer, and friendly robot assemble HUMAN.md from dark blocks on a complete grid, with pale outlines marking the unfilled cells.">
|
|
207
|
+
</p>
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
<p align="center">
|
|
212
|
+
<em>What we build may change.</em><br>
|
|
213
|
+
<em>The whys behind it remain.</em>
|
|
214
|
+
</p>
|
|
215
|
+
|
|
216
|
+
<p align="center">
|
|
217
|
+
<em>To the humans behind the whys.</em>
|
|
218
|
+
</p>
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
humanmd/__init__.py,sha256=EjjD-M-4gk8k-1B904rOOmD1bQihZK2H--U_lQ3SZLw,67
|
|
2
|
+
humanmd/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
|
|
3
|
+
humanmd/cli.py,sha256=BuCp_BHUCUtLJrSOTfBSVIlK_C3cQDEas9jXBbZnUHs,5830
|
|
4
|
+
humanmd/templates/exploration.md,sha256=Y_mMa5QGiZAfiCOrEug6zcb3az8dHuhw4F57lvZsZ80,680
|
|
5
|
+
humanmd/templates/minimal.md,sha256=jy9VPtDCxRVcbSgygq-VO2cEdEHxK9-bddco2vKpa0g,397
|
|
6
|
+
humanmd/templates/research.md,sha256=e6Wp7gAzpuV5q5Wz_JDBilsQiG14nD0F4oswMPpQCBc,845
|
|
7
|
+
humanmd/templates/software.md,sha256=dCHGDwUSOJSfxoQO7xlLw8-ENtIkGvQ_anb0yFJoipQ,679
|
|
8
|
+
humanmd-0.1.0.dist-info/METADATA,sha256=uaF_RH61UvXlAUVbA50p-rnI8o8pJMvbIjQMWWjmnII,11881
|
|
9
|
+
humanmd-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
10
|
+
humanmd-0.1.0.dist-info/entry_points.txt,sha256=1zI7ZeacRqah3snQJavwOtL4BnsAh-QkPqkhdQBK7lU,45
|
|
11
|
+
humanmd-0.1.0.dist-info/licenses/LICENSE,sha256=erQjZmKjw8Xd7Jp_QZFCzrCqFn2Q9eP9xH9Nf58Me4s,1078
|
|
12
|
+
humanmd-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HUMAN.md 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.
|